@RethinkJeff @robrix "Docs" that are just a list of API interfaces and their signatures are not docs either. They're redundant expression of something already in the code. Docs explain actual contracts and usage.
@RethinkJeff @robrix Yes, but then it's not doxygen making your docs, it's just writing your docs interspersed with the code in comments doxygen can parse. 🤷 You still have to actually write docs.
@RethinkJeff @robrix The original topic of this thread was specifically people *not doing that work* and having some clod fake it.
@dalias @robrix IMO there's a difference between writing the docs and writing the comments that those docs are based on; I've seen a lot of words written about "self documenting code" that really isn't, so this seems like a case of different experiences talking past each other T_T because I've seen a lot of people treating the two things as separate processes.
@dalias @RethinkJeff @robrix IMO, Doxygen is almost, but not quite, better than nothing. People think that they are putting good documentation in the code, but they are putting in the same old crap just in Doxygen format.
@the_other_jon @dalias @robrix Those people weren't going to write good docs anyway. This is like complaining that people will throw hammers at nails expecting them to bind boards.
@RethinkJeff @dalias @robrix I would love to see some code that generates useable documentation via Doxygen. I comment the crap out of my code, and I doubt it would make an acceptable document.
@the_other_jon @RethinkJeff @robrix Without intentionally writing comments intended as external documentation, I would not expect comments to magically yield it. Comments are normally documenting non-obvious internal things not external interface surface.
@dalias @RethinkJeff @robrix The most ironic thing about most of those docs generators is that they're pretty useful to determine functionality… for LLMs. But way less so for humans, usually.
The very brief descriptions in the code just aren't enough for static generators to extrapolate enough digestable information for anyone who *isn't* already knowledgeable in the very thing it describes, thereby it often lacks example implementations. It *needs* a human to work on good, useful docs.