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/.
Pau Espin Pedrol pespin at sysmocom.deHi, 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 at 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