On 14-05-29 08:01 AM, Lex Trotman wrote:
On 30 May 2014 00:46, Matthew Brush <mbr...@codebrainz.ca> wrote:
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.
It just needs a comment on the implementation of the API functions.
The need for an API specific macro is a separate technical thing, in
this case the purpose is to provide information to those pesky
livewares so a comment is fine. :)
Just define a snippet with the comment /* API function */ or similar
and paste it just before cutting the doxygen comment for
transplantation.
Yeah, either way, I just meant since with the related changes we would
need to put the G_MODULE_EXPORT on the public API functions anyway, we
could do something like:
#define GEANY_API_EXPORT G_MODULE_EXPORT
to provide the same meaning as the comment, provide the needed export,
and also to minimize confusion between GtkBuilder exported callbacks and
actual public API functions (same as a little comment would).
Cheers,
Matthew Brush
_______________________________________________
Devel mailing list
Devel@lists.geany.org
https://lists.geany.org/cgi-bin/mailman/listinfo/devel
