There are tools to take a well defined format and generate pretty documentation from code. What happens in real life is that people write the bare minimum that describes the interface for the function, but not how it works or how to use it beyond a few words. And then you end up with very pretty autogenerated docs that don't help you at all.

Okay but that's kind of a different problem isn't it? If people can't be bothered to comment their code properly I doubt they're going to write high quality LaTeX documentation on the side.

I find that Rust deals with that mostly well, the doc format is part of the language, the documentation generation part of the toolchain. You can even validate example code from the comments. You can enable warnings for missing documentation on methods. In my experience documentation for Rust crate is generally at least okay-ish, it generally saves me a trip into the code itself. That being said Rust prototypes are also a lot more expressive than their C counterparts (no questions about "should I free that pointer?") so that probably helps as well.

My point is that the harder you make it for people to comment their code, the less useful comments you'll get. Freeform text (where you can even whip up a ghetto table or graph with a fixed size font in a few minutes) gives you the best chance of meaningful comments.

I'm not convinced, I don't find the Rust format particularly hard to grok, it's Markdown so it looks mostly fine when viewed as plaintext. A Markdown table is pretty ghetto but on top of that it'll display nicely in the generated HTML. Also if you really want to do ascii art you can always use ``` to escape everything: https://github.com/simias/pars/blob/ce820b5af0be3091d47104cf...

I guess it does add a little bit of friction but if somebody tells me they don't write docstrings because they don't want to bother with the Markdown syntax I'd reply I'm going to assume that they're just looking for excuses at this point.