Show HN: Doczar – explicit doc generation for many languages
shenanigans.github.io
shenanigans.github.io
Also, I thought we'd learned by now that javadoc/doxygen style comments are evil? Comments are most often read in the code in plaintext, so they need to be easy to read in the code. Also, no one writes useful comments about each and every parameter to a function. "reader is the stream the function reads from" ... thanks.
Take a look at how godoc works, and emulate that. It's awesome, easy to read and write in plaintext, and produces nice html output. It does require parsing the code itself to get function names, parameter names, etc. Obviously that makes it a lot more difficult to make cross-platform, but it means writing doc strings is super easy.
I'm glad you've had a good experience with godoc. My experience with other syntax scanners in other languages is that they always get things wrong. By the time you've added tags to correct the mistakes, you've done more work than doczar would've required you to do.
"Comments are most often read in the code in plaintext" which inspired me to make a new syntax that's more human legible in the source. If you only need to document an argument as being a Stream, it's as simple and clear as `@argument/Stream reader`, no useless sentence of text necessary. edit - or `@argument/Stream* reader` or `@argument/Stream[] readers`.
That said it looks well-documented and mature.
Regarding performance, I've fed it some nasty directories and generation time is trivial. Doczar generates docs as fast as your hard drive can move them.
Thanks for looking!
Glad to here performance isn't an issue though.