3 ms·
People who write command line tools that require me to install a runtime make me sad. Also, I thought we'd learned by now that javadoc/doxygen style comments a
by NateDad 12y ago
People who write command line tools that require me to install a runtime make me sad.
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.
- hoveringGoats 12y agoIf you touch nix at all you have tons of command line tools that require runtimes. Those runtimes were just prepackaged with your distro. 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`.