Document source code

[zykh]

At the moment our source code is mainly documented with plain text comments, which is fine, but we could use everywhere one of the syntaxes out there (doxygen?) to promote clarity. Plus, the autogenerated documentation (given our codebase, I'm not sure it would work just out of the box) would act nicely as a complement to our developer guide.

Thoughts?

[clepple]

In general, I think it's a good idea. The closer the developer documentation is to the code, the better (IMHO). Someone has even parsed the NUT tree with Doxygen already: http://fossies.org/dox/nut-2.7.3/

My only gripe with Doxygen is that it is really more suited for cross-referencing the functions of a single program: if you have a tree with more than one main() , for instance, the forward links don't match the backward links, and you can easily get lost. What might make sense is to designate one driver or daemon as the primary documentation target (such as with a ./configure parameter).

As the Fossies site shows, though, it is still possible to cross-reference everything, and that would help with the next point. I would like to set things up so that we can auto-generate the documentation on checkin, and also maybe get some documentation coverage metrics for keeping track of progress.

One of the QA documents mentioned http://naturaldocs.org, but I think Doxygen is more well-known, and more regularly maintained. I'm open to other ideas, though.

Personal preference: I like the JavaDoc comment style better than using backslashes (Qt style?).

[zykh]

I looked a bit more deeply at Natural Docs: while syntax is fine (and it should be easily extensible to support other languages), the same doesn't seem to be the case for the tool:

• stable version (Perl, 4 years and counting), if I read that right, won't be developed any longer;
• new version (C#) is not officially released yet - if I recall correctly, there was a link to a compiled version (according to the author, source will be released "when new website is ready", or something like that) in SF's forum but at the moment SF is in trouble;
• limited output (though I kinda prefer the standard HTML look over Doxygen's).

Doxygen:

• JavaDoc style is fine with me. @aquette, @balooloo?
• For the moment, we could simply produce a separate documentation for each driver/api using tag files for the common parts

[EmilienKia]

Javadoc is the well-known wide-adopted format, so I think it is a good idea to adopt it.

Doxygen has advantages and disadvantages. And it is widely used and maintained. And grouping symbols using tags (or similar) can be a first step to move head.

[clepple]

@balooloo think of the Doxygen tag files as documentation "libraries", rather than markup tags. You would run Doxygen once with the common driver files, and generate a tag file from that. Then, each driver would refer to the tag file.

[EmilienKia]

A documentation system I saw some month ago is "docurium" ( https://github.com/libgit2/docurium). It is a specific documentation system developed for the library libgit2. The result is amazing : https://libgit2.github.com/libgit2/ . The feature which caught my attention is the source versionning support. When you choose a symbol, you can see its history and you can select one specific version to have the specific documentation for it.

Le jeu. 23 juil. 2015 à 14:21, Charles Lepple notifications@github.com a écrit :

@balooloo https://github.com/balooloo think of the Doxygen tag files as documentation "libraries", rather than markup tags. You would run Doxygen once with the common driver files, and generate a tag file from that. Then, each driver would refer to the tag file.

— Reply to this email directly or view it on GitHub https://github.com/networkupstools/nut/issues/212#issuecomment-124079262 .

[clepple]

@balooloo doctorium looks very interesting. I agree that the symbol version information is useful, however:

Though Docurium can generate your docs into a subdirectory, it is meant to be served from a webserver, not locally. It uses XMLHttpRequest calls...

I think we can start with the subset of JavaDoc that both Doxygen and doctorium will parse, and test out the other tools in parallel.

[zykh]

..and it only looks for headers - I think docs from other files would be useful for maintainers. (and, again, output seems limited)

However, I second Charles:

I think we can start with the subset of JavaDoc that both Doxygen and doctorium will parse, and test out the other tools in parallel.