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