4 Dec
2018
4 Dec
'18
5:10 p.m.
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
--
- Pau Espin Pedrol <pespin(a)sysmocom.de> http://www.sysmocom.de/
=======================================================================
* sysmocom - systems for mobile communications GmbH
* Alt-Moabit 93
* 10559 Berlin, Germany
* Sitz / Registered office: Berlin, HRB 134158 B
* Geschaeftsfuehrer / Managing Director: Harald Welte