Hi Neels,
On Tue, Dec 04, 2018 at 04:57:27PM +0100, Neels Hofmeyr wrote:
we have doxygen API doc in libosmocore.
[not only there, but also in other parts of the project]
The doxygen format, even though well defined, is often a distraction from code review because we often fail to get it right and need another review cycle.
that's more a question of tooling, discipline and policy. Example: I don't think I have ever rejected a patch based on doxygen related errors.
I'm looking for ways how I don't need to write review on doxygen comments. Ideas:
- We introduce hard doxygen validation in the gerrit jobs.
very good idea.
Difficulties:
- we'd probably first need to fix *all* current doxygen errors.
Sounds like a really good idea. I'm not sure, but I would hope one could selectively enable/disable doxygen warning generation similar to the way one can enable/disable classes of gcc warnings? This way one could standardize on a set of critical vs. non-critical warnings/errors.
- we'd need to add doxygen to all projects, because some of us add doxygen comments even there, and it is odd to use the format but fail to do it right.
I think whenever I write API documentation, I put it in doxygen format from the beginning.
That's probably because I still remember the suffering of converting all the various non- structured comments before we introduced doxygen to some libosmo* projects, and I didn't want to go through that again if we later expand to other projects.
I think it makes limited sense to document various static functions inside a project using Doxygen or any other API documentation tool. However, if there's a clear provider/consumer API split between two given parts of a program, and there are (or are expected to be) more than one caller/user, then those are indications for having API documentation even within one non-library program/project, such as osmo-{bts,bsc,msc,...}.
- there is no way to make sure the initial summary is ended in '.', because the script cannot understand human semantics.
that's the problem with "autobrief", right? I never had any isuses with the explicit \brief, but everybody wanted to have autobrief in place some time ago...
- I don't think anyone uses it. So we could just drop doxygen. (I find it much more useful to just browse the code with ctags.)
Definitely not. It was a lot of work and (I think) a great achievement to finally have some amount of API documentation when it was introduced. To the contrary, we should have more of it, and aim to achieve 100% coverage on all of our libraries.
Irrespective of the given format/system like doxygen, the content of course should document the *interesting* bits. Example: Of course 'msgb' is a message buffer. But does the function make assumptions about the msgb you pass to it? Does it require any of the 'l*h' pointers to be set? does it use the msgb->cb? ...
If we drop doxygen, we can just use the comments whichever way we like, omit '.' whereever and I don't need to nitpick on it. And we can drop all those \param and \a and \ref bits that break the flow of reading a C comment.
doesn't your brain automatically remove those by now when reading? I don't think I consciously notice them...
libosmocore is the only git tree actually building doxygen docs.
That's not entirely true: http://ftp.osmocom.org/api/latest/ lists also libosmo-netif, libosmo-sccp, libosmo-dsp and even osmo-gmr (Sylvain!)
- Or, I stop giving a damn about doxygen and let everyone commit all sorts of doxygen formatting errors, because no-one is reading the HTML version anyway.
I used to look at it every so often, particularly when adding new sections / code modules to it. Not so much recently, admittedly.
To me, the HTML generation is more of a (very nice) by-product. The importance is to have documentation in place. Mandating a structured format makes it easier to have it in one format, similar to having a coding style to ensure not every developer writes his code completely differently and hence putting the burden on the reader of the code.
Regards, Harald