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
_______________________________________________
Devel mailing list
Devel@lists.geany.org
https://lists.geany.org/cgi-bin/mailman/listinfo/devel
