4 ms·

Show HN: Doczar – explicit doc generation for many languages

15 points by hoveringGoats 12y ago

lsiebert 12y ago
A quick glance suggests this seems a little more flexible then doxygen or cweb in terms of what you can annotate, but it seems like it could have been built to expand on doxygen/javadoc syntax, whereas this looks like it reinvents the wheel when it comes to annotation. It seems like compatibility with doxygen + additional features might be a better choice, especially since, as a new js program, it may be slower then doxygen, which is mature and compiled from C++, when running on big/complex files. That said it looks well-documented and mature.
- hoveringGoats 12y ago
  Ah, but which should doczar be compatible with, doxygen or javadoc? A fundamental frustration I have with both of these projects is that their syntax is designed to annotate the results of a syntax scanner in their primary language, not to describe a structure from the ground up. I could potentially have worked from the syntax of an established "generalist" project such as NaturalDocs, but most of these were designed to mimic javadoc syntax. 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!
  - lsiebert 12y ago
    doxygen supports more languages then javadoc, but it definitely shows a preference for c family languages, so I feel you. Glad to here performance isn't an issue though.
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 ago
  If 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`.

15 points by hoveringGoats 12y ago

A quick glance suggests this seems a little more flexible then doxygen or cweb in terms of what you can annotate, but it seems like it could have been built to expand on doxygen/javadoc syntax, whereas this looks like it reinvents the wheel when it comes to annotation. It seems like compatibility with doxygen + additional features might be a better choice, especially since, as a new js program, it may be slower then doxygen, which is mature and compiled from C++, when running on big/complex files. That said it looks well-documented and mature.

hoveringGoats 12y ago
Ah, but which should doczar be compatible with, doxygen or javadoc? A fundamental frustration I have with both of these projects is that their syntax is designed to annotate the results of a syntax scanner in their primary language, not to describe a structure from the ground up. I could potentially have worked from the syntax of an established "generalist" project such as NaturalDocs, but most of these were designed to mimic javadoc syntax. 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!
- lsiebert 12y ago
  doxygen supports more languages then javadoc, but it definitely shows a preference for c family languages, so I feel you. Glad to here performance isn't an issue though.

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 ago
If 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`.