[Geany-Devel] Another set of Plugin API questions

[Lex Trotman]

On 26 May 2014 09:38, Matthew Brush <mbrush at codebrainz.ca> wrote:
> Hi,
>
> Is it fair to say that any function that is not represented in
> `geanyfunctions.h`/`plugindata.h` and any types that are not documented with
> a `/**` or other Doxygen comment are to be considered "private" with respect
> to the plugin API?

My understanding, and the documentation (as you mention below says)
that this is the case.  But don't presume that there are no mistakes
in the construction of the API public functions as you point out
below.  It might need adjustment.


>
> For example there are some types/enums in `build.h` that have comments that
> start with `/* *` (note the space in-between asterisks). I presume that's to
> keep them from being made "public" by not allowing Doxygen to scan them. Is
> that accurate? If that's the case, how do we handle that some of the public
> functions in `build.h` require these enums in order to be useful (ie. use
> parameters of those types)?

It sounds like its a mistake, remember that build.h additions to the
API were removed, then put back, and those items seem to have been
missed in the process.  Anything (typedef, struct, enum etc) that is
needed to use public functions should be public and documented.

Where a struct/typedef may be public but validly not have the members
documented is the case where it is returned from an API function to be
passed to another API function without its contents being used.  The
struct etc should be documented as being "opaque" in this case to make
it clear that its not a mistake that the members were not part of the
API.


>
> Another example is `filetype_id` which is the enum type in `filetypes.h`
> that holds the various filetype IDs (ex. GEANY_FILETYPES_C,
> GEANY_FILETYPES_HTML, etc.). It's completely undocumented, but is used (as
> gint type) in functions such as `filetypes_index()`. Is it fair to say this
> whole enum is private, or should it rather be considered public since it was
> exposed to plugins via the include of `filetypes.h` in `geanyplugin.h`?

Again sounds like its a mistake, since the example for
`filetypes_index()` uses `GEANY_FILETYPES_C`.  At least the enum
should be documented.  A lazy person like me would say "the enum
members are part of the API, even though they are not individually
documented since their use is obvious" in that documentation.

>
> Along these lines, in `geanyplugin.h` there are includes of many common
> headers, with a comment about only including headers that expose types, not
> just functions. Having had these headers exposed to plugins (and also being
> documented in Doxygen API docs), does that mean that every
> symbol/function/type in these headers is part of the public API and should
> not be hidden inside of private headers, for example (see other thread about
> private headers). Is it a plugin bug if they used any undocumented
> symbols/functions/signals/types?

Functions that are not doxygened in *either* the .h or .c file are not
meant to be in the API.  So they can safely be made private (from the
point of view of the API).  IIUC the tradition was for functions to be
documented in the .c files rather than the .h files  since functions
in the API did not need to be in the header, since the macro trick was
intended to make them visible, but types only exist in the headers, so
they need documenting there.

>
> FWIW, I noticed the plugin API docs says right on the main page:
>
>> Warning
>>   Do not use any symbol not in the documentation - it may change.
>
> And my final question: do we support individual includes of Geany's headers
> that were available? For example, if someone, for some crazy reason wanted
> to move `struct GeanyDocument` to `document-blah.h` (fake example), is it a
> plugin bug if they directly included "document.h" where this type was
> previously, or is it an API bug because we moved the type to another file,
> even though we added an and include for the new header inside the central
> include file `geanyplugin.h`?

If the type was documented as being in document.h then its a bug or
API break in Geany for it to be moved because it no longer conforms to
the documented API.

So that suggests that the "single include" approach is the best, then
so long as the type is included it doesn't matter from where.  Geany
is then free to move stuff around as it requires.  So, I would agree
with a "single plugin" approach.  That should be done once (being an
API break).  It isn't a big API break though, only plugin files that
don't include "geanyplugin.h" will be affected.

Cheers
Lex

PS thanks for the effort to clean up the API.

>
> Cheers,
> Matthew Brush
> _______________________________________________
> Devel mailing list
> Devel at lists.geany.org
> https://lists.geany.org/cgi-bin/mailman/listinfo/devel