Hi,
There's some stuff in the plugin API docs that are documented but provide no functionality. There's also some stuff that's used by plugins, which is not documented.
One example is support.h. This shows up in the plugin API, yet there is nothing available in it.
Another example is GeanyFilePrefs, where the struct is documented in the API, but no members are documented. There are some plugins using members of this, despite them not being documented (ex. ao_blanklines.c:67), so maybe we should put them into the documented API.
IMO, if a file has no "public" functions or a struct has no "public" members, these should not show up in the API docs *at all*, otherwise it's a little confusing what's available and what's just not documented properly.
Any thoughts?
Cheers, Matthew Brush
On 28 August 2011 09:29, Matthew Brush mbrush@codebrainz.ca wrote:
Hi,
There's some stuff in the plugin API docs that are documented but provide no functionality. There's also some stuff that's used by plugins, which is not documented.
One example is support.h. This shows up in the plugin API, yet there is nothing available in it.
All support.h does is to import the glib i18n interface or generates null macros if for some reason gettext isn't available. It points to the glib i18n documentation for the working interface and the null macros don't do anything so there is nothing to document :-)
Another example is GeanyFilePrefs, where the struct is documented in the API, but no members are documented. There are some plugins using members of this, despite them not being documented (ex. ao_blanklines.c:67), so maybe we should put them into the documented API.
Yes, either the structure documentation should say all members are intended to be available, or the ones meant to be available should be documented. That way there is a prompt to avoid ABI breakage when changing the structure. ATM I would miss the comment and might not add to the end of the structure or may not increment the ABI.
IMO, if a file has no "public" functions or a struct has no "public" members, these should not show up in the API docs *at all*, otherwise it's a little confusing what's available and what's just not documented properly.
Generally true.
Any thoughts?
Not many :-)
Cheers Lex
On 08/27/2011 07:29 PM, Lex Trotman wrote:
On 28 August 2011 09:29, Matthew Brushmbrush@codebrainz.ca wrote:
Hi,
There's some stuff in the plugin API docs that are documented but provide no functionality. There's also some stuff that's used by plugins, which is not documented.
One example is support.h. This shows up in the plugin API, yet there is nothing available in it.
All support.h does is to import the glib i18n interface or generates null macros if for some reason gettext isn't available. It points to the glib i18n documentation for the working interface and the null macros don't do anything so there is nothing to document :-)
But isn't there an easy way to hide it from the plugin API docs (ie. no Doxygen comments)? What use is some file/struct documented in the API docs if none of its functions/members are accessible?
Another example is GeanyFilePrefs, where the struct is documented in the API, but no members are documented. There are some plugins using members of this, despite them not being documented (ex. ao_blanklines.c:67), so maybe we should put them into the documented API.
Yes, either the structure documentation should say all members are intended to be available, or the ones meant to be available should be documented. That way there is a prompt to avoid ABI breakage when changing the structure. ATM I would miss the comment and might not add to the end of the structure or may not increment the ABI.
At least all members currently used by plugins should be documented in the API docs, no?
Cheers, Matthew Brush
[...]
All support.h does is to import the glib i18n interface or generates null macros if for some reason gettext isn't available. It points to the glib i18n documentation for the working interface and the null macros don't do anything so there is nothing to document :-)
But isn't there an easy way to hide it from the plugin API docs (ie. no Doxygen comments)? What use is some file/struct documented in the API docs if none of its functions/members are accessible?
Clearly the comment on support.h and my explanation need some improvement. IIUC the intention is that support.h makes *all* of gi18n-lib.h available. That is what defines the interface, but of course we can't comment the glib header. This needs to be more clearly stated.
The alternate macros defined in support.h (note they are in a #else) define some of the same interface to prevent compile errors in case gettext isn't available, but they do nothing. Maybe they should be documented to make it clearer that those macros/functions can be safely used even if gettext isn't available, but the basic definition is in the glib header.
Another example is GeanyFilePrefs, where the struct is documented in the API, but no members are documented. There are some plugins using members of this, despite them not being documented (ex. ao_blanklines.c:67), so maybe we should put them into the documented API.
Yes, either the structure documentation should say all members are intended to be available, or the ones meant to be available should be documented. That way there is a prompt to avoid ABI breakage when changing the structure. ATM I would miss the comment and might not add to the end of the structure or may not increment the ABI.
At least all members currently used by plugins should be documented in the API docs, no?
Well if they are used then they should be documented unless someone objects. That way people modifying Geany and building bindings know to avoid changing them :-)
Cheers Lex