On 14-05-29 05:56 AM, Nick Treleaven wrote:
On 26/05/2014 01:23, Lex Trotman wrote:
>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.
Its neater to have them in the public .h file sure, but I suggest that
they are going to be less likely to be kept up to date that way. Most
of the editing happens in the .c files (I don't even open the .h much
of the time) so the doxygen comments in headers become out of sight,
out of mind.
Agree, that's an important reason. Another benefit is less rebuilding
due to header file changes.
It's unclear if you're actually against $topic or just pointing out more
reason for keeping the public API comments private.
FWIW, the first point will/would be somewhat offset by the fact that
public functions could/would have G_MODULE_EXPORT (or we could make some
macro like GEANY_API_EXPORT or such for readability) to remind that a
public function is being edited and there's sure to be a comment to edit
as well. What's more, it's actually not that hard to always in all cases
open a single header file and check if you broke the public API/docs,
compared to all the other stuff required to making changes.
The extra rebuilding would be offset by having the private and public
stuff split into separate files, some files wouldn't even need to
include the public headers anymore and so wouldn't trigger rebuilding as
many files. In addition, if we were really worried about build
times/include dependencies, we could use forward declaration in quite a
few headers that just use an opaque pointer to a public type instead of
including the whole header. I think overall we could actually reduce the
amount of re-building required in addition to making the API comments
accessible to the public API users who they're meant for.
Cheers,
Matthew Brush
_______________________________________________
Devel mailing list
Devel@lists.geany.org
https://lists.geany.org/cgi-bin/mailman/listinfo/devel
