[Geany-Devel] Another set of Plugin API questions

Matthew Brush mbrush at xxxxx
Sun May 25 23:38:04 UTC 2014


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?

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

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

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?

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

Cheers,
Matthew Brush


More information about the Devel mailing list