Hi,
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?
Cheers, Matthew Brush
On 26 May 2014 09:50, Matthew Brush mbrush@codebrainz.ca wrote:
Hi,
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?
They are intended to be "accessible" via the generated doxygen documentation, its not necessary to read the source.
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.
Does anyone feel really strongly about this?
No, but if you do move them, leave a comment in the .c file on any API visible function as a note that its in the API, and should not be changed without changing the API docs and bumping the API/ABI.
Cheers Lex
Cheers, Matthew Brush _______________________________________________ Devel mailing list Devel@lists.geany.org https://lists.geany.org/cgi-bin/mailman/listinfo/devel
On 14-05-25 05:23 PM, Lex Trotman wrote:
On 26 May 2014 09:50, Matthew Brush mbrush@codebrainz.ca wrote:
[snip]
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.
If, in future changes, we used the `G_MODULE_EXPORT` stuff, and kept it at the site of the definition (in the C file), it might provide a queue for anyone changing it that it has related boilerplate, being an exported/public function. It might help a bit here at least.
Cheers, Matthew Brush
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.
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
On 30 May 2014 00:46, Matthew Brush mbrush@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.
Cheers Lex
Am 26.05.2014 01:50, schrieb Matthew Brush:
Hi,
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?
Hello,
I can't say I feel overly strong but my experience is that when implementation and comments are split that they begin to drift apart sooner or later. I suggest keeping things as they are unless there is a compelling technical advantage. We do a half decent job at documentation (which is better than 90% of other FOSS projects) and we should not risk that.
The reference documentation is the doxygen generated html/pdf/etc. It is in many ways superior to headers+comments. The API is available online, and we could also install it on make install, so that plugin authors are not required to download anything.
Best regards.
On 14-05-29 08:01 AM, Lex Trotman wrote:
On 30 May 2014 00:46, Matthew Brush mbrush@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
On 14-05-29 11:58 AM, Thomas Martitz wrote:
Am 26.05.2014 01:50, schrieb Matthew Brush:
Hi,
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?
Hello,
I can't say I feel overly strong but my experience is that when implementation and comments are split that they begin to drift apart sooner or later. I suggest keeping things as they are unless there is a compelling technical advantage. We do a half decent job at documentation (which is better than 90% of other FOSS projects) and we should not risk that.
I agree somewhat, but it's actually not very hard to open the related header and check when changing the code, especially since often changing the API documentation means adding a new function, or changing the semantics/signatures of a function, or adding/changing a structure/type, which all requires editing the header anyway, so it's actually not really much extra work.
As far as technical advantage, it causes less misleading comments in the source (eg. documenting `@file foo.h` in the foo.c source file), avoids users having to get a copy of the Doxygen docs for the correct version, and finally to keep all the public API comments in the same public header file, instead of the current way where types (structs, typedefs, etc.) are necessarily documented in the header, but functions are documented in the internal non-installed source files.
The reference documentation is the doxygen generated html/pdf/etc. It is in many ways superior to headers+comments. The API is available online, and we could also install it on make install, so that plugin authors are not required to download anything.
Not everything is actually documented in Doxygen though, so one often needs to reference the headers anyway, plus the online docs are for the latest release and not the development version of Geany (AFAIK), and additionally, installing the docs on make install (unconditionally) would mean we require the user to have at least Doxygen (plus Qt and all the stuff it requires) installed. But I agree we should (also) make the API docs installable and maybe for packagers to make them part of the -dev package for Geany if they wanted to.
Cheers, Matthew Brush
Am 29.05.2014 21:21, schrieb Matthew Brush:
On 14-05-29 11:58 AM, Thomas Martitz wrote:
Am 26.05.2014 01:50, schrieb Matthew Brush:
Hi,
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?
Hello,
I can't say I feel overly strong but my experience is that when implementation and comments are split that they begin to drift apart sooner or later. I suggest keeping things as they are unless there is a compelling technical advantage. We do a half decent job at documentation (which is better than 90% of other FOSS projects) and we should not risk that.
I agree somewhat, but it's actually not very hard to open the related header and check when changing the code, especially since often changing the API documentation means adding a new function, or changing the semantics/signatures of a function, or adding/changing a structure/type, which all requires editing the header anyway, so it's actually not really much extra work.
It's not hard but it'll be still be forgotten/missed. We're just human beings.
As far as technical advantage, it causes less misleading comments in the source (eg. documenting `@file foo.h` in the foo.c source file), avoids users having to get a copy of the Doxygen docs for the correct version, and finally to keep all the public API comments in the same public header file, instead of the current way where types (structs, typedefs, etc.) are necessarily documented in the header, but functions are documented in the internal non-installed source files.
Neither of those are technical or (IMO) compelling.
Best regards
On 14-05-29 12:33 PM, Thomas Martitz wrote:
Am 29.05.2014 21:21, schrieb Matthew Brush:
On 14-05-29 11:58 AM, Thomas Martitz wrote:
Am 26.05.2014 01:50, schrieb Matthew Brush:
Hi,
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?
Hello,
I can't say I feel overly strong but my experience is that when implementation and comments are split that they begin to drift apart sooner or later. I suggest keeping things as they are unless there is a compelling technical advantage. We do a half decent job at documentation (which is better than 90% of other FOSS projects) and we should not risk that.
I agree somewhat, but it's actually not very hard to open the related header and check when changing the code, especially since often changing the API documentation means adding a new function, or changing the semantics/signatures of a function, or adding/changing a structure/type, which all requires editing the header anyway, so it's actually not really much extra work.
It's not hard but it'll be still be forgotten/missed. We're just human beings.
But if you can forget it when you're editing the function/type declaration, why can't you forget it when you're editing the function definition? I just mean, either way, you need to look at the function/type and either update the comment or not, regardless where it's placed. Plus having a little comment or macro that hints that the function is public as discussed in the other messages would provide a bit of backup for people who aren't very conscious about whether they're editing public API or keeping the docs in sync.
As far as technical advantage, it causes less misleading comments in the source (eg. documenting `@file foo.h` in the foo.c source file), avoids users having to get a copy of the Doxygen docs for the correct version, and finally to keep all the public API comments in the same public header file, instead of the current way where types (structs, typedefs, etc.) are necessarily documented in the header, but functions are documented in the internal non-installed source files.
Neither of those are technical or (IMO) compelling.
Ok, not super technical, but more compelling than "I'm too lazy to open the header file/update the documentation if it's not directly above one place I edit (instead of the other place I most likely have to edit)" :)
Cheers, Matthew Brush
[...]
Ok, not super technical, but more compelling than "I'm too lazy to open the header file/update the documentation if it's not directly above one place I edit (instead of the other place I most likely have to edit)" :)
Different people have different workflows, some open everything, some only open the minimum.
Everything the plugin writer needs should be in the doxygen API docs. If its not fix that, don't make the plugin writer read the source.
After looking at the discussions I have changed my mind and think the comments should *NOT* be moved to the header.
Cheers Lex
Cheers, Matthew Brush
Devel mailing list Devel@lists.geany.org https://lists.geany.org/cgi-bin/mailman/listinfo/devel
On 14-05-29 04:37 PM, Lex Trotman wrote:
[...]
Ok, not super technical, but more compelling than "I'm too lazy to open the header file/update the documentation if it's not directly above one place I edit (instead of the other place I most likely have to edit)" :)
Different people have different workflows, some open everything, some only open the minimum.
Yeah, I guess I just see the public headers as "the official interface description" of the API, so it follows that (IMO) all relevant in-source documentation/comments that describe what's in the API headers should be available in them, instead of scattered into various places. If you have the headers, you can use/understand the interface kind of idea.
Everything the plugin writer needs should be in the doxygen API docs. If its not fix that, don't make the plugin writer read the source.
After looking at the discussions I have changed my mind and think the comments should *NOT* be moved to the header.
OK, so that's one +1 for only some of the doc-comments being in the public headers (structs, enums, etc.), some being in the private/not-installed source files (functions), and some being in separate private/non-installed, non-code files (signals), and then requiring the user to have an Internet connection, Doxygen, or a combination of the not-installed source files and the installed API headers to be able to access the docs (ie status quo).
Does anyone else feel strongly either way?
FWIW, I don't really feel super strongly, it's just an idea that I had to help make the public headers more useful for the only people they're intended for (ie. plugin developers), along with the other stuff I want to work on like not exposing private stuff, ensuring all public stuff is properly documented, etc. None if this other stuff really hinges on moving the comments to the headers, it's just a parallel idea.
Cheers, Matthew Brush
Le 29/05/2014 21:43, Matthew Brush a écrit :
[...]
It's not hard but it'll be still be forgotten/missed. We're just human beings.
But if you can forget it when you're editing the function/type declaration, why can't you forget it when you're editing the function definition? I just mean, either way, you need to look at the function/type and either update the comment or not, regardless where it's placed. Plus having a little comment or macro that hints that the function is public as discussed in the other messages would provide a bit of backup for people who aren't very conscious about whether they're editing public API or keeping the docs in sync.
[...]
Ok, not super technical, but more compelling than "I'm too lazy to open the header file/update the documentation if it's not directly above one place I edit (instead of the other place I most likely have to edit)" :)
It's highly unlikely to edit the declaration, but likely to change the implementation. If you change the signature, you break the API, but if you simply change the implementation you may add a further notice on a limitation or a feature, or note that the function now accepts more inputs or something. I mean, touching that API happens 100% of the time in the implementation side, while only <100% on the declaration side. Also, I think 99% of the API docs edits don't follow an API breakage (e.g. not touching the declaration).
And I agree with Thomas that moving it farther from implementation will lower the probability of updating (just because you don't see the docs and notice it's not good enough).
About where they should be, I'm used to placing them above the *declaration*, no matter where it is. And the above reason applies.
Apart that, I have not much to add to initial comments from Lex and Thomas. I don't feel strongly about this, but I don't think it has much advantages (realistically I think all developers will look at the generated docs anyway[1]), while I'm afraid it may have pitfalls.
My 2¢, Colomban
[1] Note that GLib and GTK don't have docs in the headers, so most people will have to look at those docs from time to time anyway.