On 26 May 2014 09:38, Matthew Brush mbrush@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@lists.geany.org https://lists.geany.org/cgi-bin/mailman/listinfo/devel

On 14-05-25 04:38 PM, Matthew Brush wrote:

[snip] 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`?

For a real life example of this, consider this comment from the recent `header-cleanup` merge:

https://github.com/geany/geany/commit/4efcbab33234d13a7c6d1dea2901535d9317e4...

And the likewise patch/PR for the plugin in GP:

https://github.com/codebrainz/geany-plugins/commit/307880c0778e27d191305ec6c...

In this case I moved `GeanyApp` which was in `geany.h` (which was exposed to plugins via `geanyplugin.h`) to `app.h` of its own, but it broke GeanyLua that included all the stuff that `geanyplugin.h` would've provided it, individually.

Is this a plugin bug or a public API break/bug?

Cheers, Matthew Brush