[Geany-Devel] [RFC]: Public API comments in headers

Matthew Brush mbrush at xxxxx
Sun May 25 23:50:15 UTC 2014


As part of working on cleaning up the exposed API to plugins I got to 
thinking about where our comments are located. While it's nice to keep 
the API-documentation-comments right at the definitions of the functions 
in their respective .c source files, since we only install the headers 
as a public reference (not even the plugin API docs IIUC), should we not 
move the API-documentation-comments, that we already diligently ensure 
exist and are fairly complete, into the headers where they are 
accessible to plugin developers?

If we moved to having public headers that just included actual public 
symbols, I think it would be advantageous to have those headers totally 
commented/documented rather than requiring the user to download Geany's 
source code and cross-reference functions in it to access the 
comments/docs, or getting hold of the generated Doxygen API documentation.

Does anyone feel really strongly about this?

Matthew Brush

More information about the Devel mailing list