

Show HN: Doczar – explicit doc generation for many languages - hoveringGoats
http://shenanigans.github.io/node-doczar/docs/property/doczar/spare/README/index.html

======
NateDad
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
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`.

------
lsiebert
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
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
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.

