25 Feb
2025
25 Feb
'25
2:57 p.m.
Hi,
it came up again in gerrit again.
Currently the osmocom style states doxygen style comments should be done in the .c file.
Doxygen are those comments:
/*! a brief description of the function
* \param something Some description of the use
* \return 0 if ...
*/
Doxygen takes those comments and generates a html documentation of the code.
I would like to change it to have those in the headers files instead (when the function in
included in a header file).
When using the doxygen comments only for doyxen, for sure, there isn't a difference
between
having it in .c or in .h files.
But when using IDEs or language servers, they usually only parses headers files and
the .c files of the current active project (e.g. osmo-sgsn),
but not the .c files of other projects (libosmocore).
On the downside I only see the problem of increasing the size of header files, but I
don't see
an issue in here.
Any thoughts?
Best,
lynxis
26 Feb
26 Feb
1:36 p.m.
Hi,
while I wouldn't be against it if we were to start writing a whole new
project, we have tons and tons of files already doing doxygen in the .c
files, so I wouldn't start now doing differently and have mixed
codebase. Also moving all current doxygen documentation to header files
sounds like a huge tasks with lots of changes in lots of places, so it
looks like a no-go to me.
Moreover, I don't really see a good reason for moving documentation to
header files other than:
* "My foobar editor decides it only parses header files"
* A user may want to inspect documentation through installed -dev
packages in /usr/include/osmocom/.
Is actually doxygen explicitly enforcing the API documentation to be on
header files? I doubt it.
There's also some benefits of having it in .c files:
* Documentation is next to the implementation, so one can quickly
validate the implementation and formal behavior of the function
* Way shorter header files wich allow seing the full set of APIs
available with a quick glance at the screen.
* Functions can be declared in several headers/places (we hopefully
don't do this).
So not like I have a strong opinion on this, but I don't think it really
makes sense to change the current approach right now?
Regards,
Pau
--
- Pau Espin Pedrol <pespin(a)sysmocom.de> http://www.sysmocom.de/
=======================================================================
* sysmocom - systems for mobile communications GmbH
* Siemensstr. 26a
* 10551 Berlin, Germany
* Sitz / Registered office: Berlin, HRB 134158 B
* Geschaeftsfuehrer / Managing Director: Harald Welte
28 Feb
28 Feb
11:58 a.m.
Hi all,
I'm pretty much with Pau here:
On Wed, Feb 26, 2025 at 01:36:18PM +0100, Pau Espin Pedrol wrote:
Moreover, I don't really see a good reason for
moving documentation to
header files other than:
* "My foobar editor decides it only parses header files"
* A user may want to inspect documentation through installed -dev packages
in /usr/include/osmocom/.
[...]
There's also some benefits of having it in .c files:
* Documentation is next to the implementation, so one can quickly validate
the implementation and formal behavior of the function
* Way shorter header files wich allow seing the full set of APIs available
with a quick glance at the screen.
* Functions can be declared in several headers/places (we hopefully don't do
this).
So not like I have a strong opinion on this, but I don't think it really
makes sense to change the current approach right now?
I also don't have a super strong opinion if we were about to create a policy for
software that hasn't been written yet. But given we have a massive codebase with
comments in the .c files, I do not think it is a wise investment to convert the entire
codebase.
Regards,
Harald
--
- Harald Welte <laforge(a)osmocom.org> https://laforge.gnumonks.org/
============================================================================
"Privacy in residential applications is a desirable marketing option."
(ETSI EN 300 175-7 Ch. A6)
5 Mar
5 Mar
1:58 p.m.
Hi,
while I wouldn't be against it if we were to start
writing a whole new
project, we have tons and tons of files already doing doxygen in the .c
files, so I wouldn't start now doing differently and have mixed
codebase. Also moving all current doxygen documentation to header files
sounds like a huge tasks with lots of changes in lots of places, so it
looks like a no-go to me.
I don't see the requirement to move all function documentation to the header in one
go.
New code should have it in the header, old code can keep it until someone moves it (or
touches it).
Moreover, I don't really see a good reason for
moving documentation to
header files other than:
* "My foobar editor decides it only parses header files"
* A user may want to inspect documentation through installed -dev
packages in /usr/include/osmocom/.
It comes down to those two points. I guess most editors doesn't
take up the documentation, when located in a distant directory which isn't
part of the current project.
I also find it strange that I've have to read the code (.c file) of a function to see
the documentation instead of just looking into the header file.
Is actually doxygen explicitly enforcing the API
documentation to be on
header files? I doubt it.
AFAIK, doxygen doesn't care, it's about the documentation style.
Best,
lynxis
27 Feb
27 Feb
8:06 p.m.
BTW, for me, the argument isn't so much doxygen. I never use that HTML and if
anyone does, please raise your hand. For me it's about reading the source tree.
(I would very much enjoy dropping the weird doxygen syntax and markers)
There may also be the aspect of the license applying only to the .c files. IIUC
.h files are considered flat compiling necessity, not substance of a project.
I'm not sure about this / don't feel strong about that aspect.
My two main strong opinions are opposing each other:
1. when hacking on our code, i enjoy that a .h has only the terse list of
actual API without long comments in-between. It makes it easy to get a good big
picture of the API very rapidly. The doc is just one ctags jump away.
2. when using other libraries, i enjoy when the .h file already explains
everything i need to know about the function arguments. Because I don't have
the .c file anywhere near.
A good example for both is talloc. Very useful to read the .h for docs. But it
also took me a very long time to get a big picture of the API. Years later I
was still finding functions i wished i had known about sooner.
My preference for either is not strong enough to want to change how we're doing
it in osmocom.
~N
8:23 p.m.
Neels wrote:
BTW, for me, the argument isn't so much doxygen. I
never use that HTML and if
anyone does, please raise your hand. For me it's about reading the source tree.
(I would very much enjoy dropping the weird doxygen syntax and markers)
Me too! I agree with every word Neels said in those 3 lines, that's
exactly how I feel about those comments. Life would be so much easier
if I could write simple comments without all that weird doxygen-ese.
M~
28 Feb
28 Feb
11:55 a.m.
Hi Neels,
On Thu, Feb 27, 2025 at 08:06:07PM +0100, Neels Hofmeyr wrote:
BTW, for me, the argument isn't so much doxygen. I
never use that HTML and if
anyone does, please raise your hand. For me it's about reading the source tree.
(I would very much enjoy dropping the weird doxygen syntax and markers)
I actually open the rendered html (as we publish it on
https://ftp.osmocom.org/api/latest/)
every so often.
--
- Harald Welte <laforge(a)osmocom.org> https://laforge.gnumonks.org/
============================================================================
"Privacy in residential applications is a desirable marketing option."
(ETSI EN 300 175-7 Ch. A6)
108
days inactive
116
days old
6 comments
5 participants
participants (5)
-
Alexander 'lynxis' Couzens -
Harald Welte -
Mychaela Falconia -
Neels Hofmeyr -
Pau Espin Pedrol