5 Dec
2018
5 Dec
'18
8:59 a.m.
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
--
- Harald Welte <laforge(a)gnumonks.org> http://laforge.gnumonks.org/
============================================================================
"Privacy in residential applications is a desirable marketing option."
(ETSI EN 300 175-7 Ch. A6)