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/.
Neels Hofmeyr nhofmeyr at sysmocom.deHi 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
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 833 bytes
Desc: not available
URL: <http://lists.osmocom.org/pipermail/openbsc/attachments/20181204/76053e4d/attachment.bin>