3 ms·
I'm leaning towards agreement with you, especially for embedded API docs in code. I've been using Scribble for embedded API docs for years,[1] and the formatte
by neilv 8y ago
I'm leaning towards agreement with you, especially for embedded API docs in code.
I've been using Scribble for embedded API docs for years,[1] and the formatted result looks great, and is very powerful and extensible (Scribble is actually a better LaTeX), but it's not nearly as readable in code as it could be.
I think I actually preferred my earlier three-comment-character-Texinfo format I had before, and I even wrote a converter to Scribble for it (so that it would look idiomatic), except Texinfo format just couldn't handle Racket types.
Now that I've put Racket on hold while I Rust a bit, in the interests of job-hunting, I'm happy to see Rust is using Markdown (coincidentally, also with the three-comment-character prefix).
[1] Here's one formatted example, everything coming from the code files and package metadata, no separate documentation files: https://www.neilvandyke.org/racket/roomba/ https://www.neilvandyke.org/racket/roomba/