Adding doxygen style comments to header files
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
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@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
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@osmocom.org> https://laforge.gnumonks.org/ ============================================================================ "Privacy in residential applications is a desirable marketing option." (ETSI EN 300 175-7 Ch. A6)
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
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
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~
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@osmocom.org> https://laforge.gnumonks.org/ ============================================================================ "Privacy in residential applications is a desirable marketing option." (ETSI EN 300 175-7 Ch. A6)
participants (5)
-
Alexander 'lynxis' Couzens -
Harald Welte -
Mychaela Falconia -
Neels Hofmeyr -
Pau Espin Pedrol