[Geany-devel] Minor problems with plugin API docs

[Lex Trotman]

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 :-)

>
> 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