[Geany-devel] Minor problems with plugin API docs

[Matthew Brush]

On 08/27/2011 07:29 PM, Lex Trotman wrote:
> On 28 August 2011 09:29, Matthew Brush<mbrush at 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