Hi all,
we have doxygen API doc in libosmocore. 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.
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. Difficulties: - we'd probably first need to fix *all* current doxygen 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. - there is no way to make sure the initial summary is ended in '.', because the script cannot understand human semantics.
- 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.)
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.
libosmocore is the only git tree actually building doxygen docs.
OTOH, when removing doxygen, would we also drop all those \file and other section markers?
- 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.
thoughts welcome...
~N
Hi,
On 12/4/18 4:57 PM, Neels Hofmeyr wrote:
Hi all,
we have doxygen API doc in libosmocore. 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.
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. Difficulties:
- we'd probably first need to fix *all* current doxygen 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.
- there is no way to make sure the initial summary is ended in '.', because the script cannot understand human semantics.
I think it makes sense to enable doxygen validation during jenkins.sh, but on the long run, no rush (like I did with --enable-werror 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.)
I have used it a few times. You may not use it because you are used to the libosmo* implementation, but users of these libraries don't need to care about implementation details, and in this case it's useful having the doxygen API. I used doxygen API several times when building apps that use C library APIs (ffmpeg and alike I can think of now). So think about use case: somebody not really interested in developing libosmocore but willing to use some of its features in his own project (msgb, timers, main loop, fsm, etc.).
libosmocore is the only git tree actually building doxygen docs.
IIRC libosmo-abis or/and libosmo-netif do too.
In general, my opinion regarding this topic is: even if w dont' currently build doxygen, allow people to use doxygen formatting to ease enabling it later. Don't be too picky about formatting, small bits can always be improved later if needed. I'm personally happy to receive comments on some doxygen formatting I do wrong.
Some related topic: I sometimes have the feeling the doxygen html documentation we generate is not really visible and most people may not even know where it is. I'd need to check where it is located right now. Not sure how to give it more visibility though.
Regards, Pau
only for libosmocore
actually I see now there are: libosmocore libosmodsp libosmonetif libosmosccp osmo-gmr
libosmosdp? also interesting: on my disk it's called 'libosmo-netif' and 'libosmo-sccp' with dashes.
On Tue, Dec 04, 2018 at 05:10:13PM +0100, Pau Espin Pedrol wrote:
know where it is. I'd need to check where it is located right now. Not sure how to give it more visibility though.
Doing the typical redmine search dance: type "Documentation", check [x] Search titles only, click "_Wiki_pages_" https://osmocom.org/projects/cellular-infrastructure/wiki/Guidelines_for_API...
Just added a link from the Osmocom Manuals wiki page. (btw, osmith, that wiki page still explains stuff how it was before the move of manuals)
~N
On 12/5/18 12:07 PM, Neels Hofmeyr wrote:
(btw, osmith, that wiki page still explains stuff how it was before the move of manuals)
Updated, thanks for the pointer.
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
On Wed, Dec 05, 2018 at 08:59:29AM +0100, Harald Welte wrote:
- 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?
Even for explicit \brief, you should still end the sentence in a dot. One of the two: either the same (next line bleeds into \brief) or we had a problem if the first summary spans more than one line and was cut off by \brief? In any case, the logic was so that I came to the conclusion that without having to write '\brief', things were more or less similar.
But I really don't understand why anyone would write an API comment and choose to not end a sentence in a full-stop, and why many of you particularly do that for the first sentence only. That's a very weird social phenomenon :P
My particular taste problem with '\brief' was that I dislike any and all of the doxygen formatting breaking the flow of reading API and writing doc in C comment. Worst of all is '\a', it reads like the english 'a', and totally messes up reading. Shouldn't be that hard for doxygen to just automatically find all the defined names and highlight them.
doesn't your brain automatically remove those by now when reading?
They reliably throw me off every time. Maybe because my personal nature tends towards "too obsessed with details".
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!)
yep, also just noticed, thx
~N
-
Harald Welte -
Neels Hofmeyr -
Oliver Smith -
Pau Espin Pedrol