This is merely a historical archive of years 2008-2021, before the migration to mailman3.
A maintained and still updated list archive can be found at https://lists.osmocom.org/hyperkitty/list/OpenBSC@lists.osmocom.org/.
Harald Welte laforge at gnumonks.orgHi 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 at gnumonks.org> http://laforge.gnumonks.org/
============================================================================
"Privacy in residential applications is a desirable marketing option."
(ETSI EN 300 175-7 Ch. A6)