4 ms·
Yeah, the other thread, from week ago, and comment from two hours ago. I had the time to already forget about your project and drown my comment about it with ot
by dozzie 10y ago
Yeah, the other thread, from week ago, and comment from two hours ago. I had the
time to already forget about your project and drown my comment about it with
other comments before you replied there.
As I said here already, I can't tell how to use it and what to use it for.
Let's assume I have a project that already has some code and no documentation.
First thing I want to know is what kind of artifacts your thing produces. This
is important and there are several valid options, which include "HTML pages to
publish on a generic web page", "HTML to be published on readthedocs", and
"man pages".
Then I want to know how to start actually using the tool. Remember: I don't
have any documentation structure and I know nothing about your tool. I don't
know if it uses documenting comments (JavaDoc/Doxygen style), separate text
files (SGML/asciidoc style), or maybe a combination of these (like Sphinx
does). I don't know how to run your tool to generate the thing and how to
control its output.
Then there is the issue of semantic markup. Any sensible documentation tool
allows the writer to distinguish several important types of things, like
functions, classes, and modules, and it does so in a single, designated way
that results in always looking the same. I haven't seen anything like that in
your tool, which means I, as an author, need to constantly remember how I mark
the functions and modules.
You should compare how your documentation looks standing beside Doxygen,
Sphinx, or much simpler asciidoc and POD (Perl's plain old documentation).