[Geany-devel] Adding a list of filetypes into devel documentation?
mbrush at xxxxx
Tue Aug 16 02:19:35 UTC 2011
On 08/15/2011 03:45 PM, Lex Trotman wrote:
>> If I get some time, I could try and do this. Is anybody opposed to putting
>> the API docs in reStructuredText files and generating the API docs using
>> Sphinx? I've been using this for the Python bindings and it's quite nice
>> and easy, and there's support for C domain as well.
> I personally don't care, but being cautious, can you provide a C example?
It's just the "Plugin Howto" and one function from "dialogs.h", but it
conveys the idea I think.
> As we said in another thread there probably needs to be discussion on
> what is exposed of the Geany internal design, otherwise exposing it
> will freeze the design or cause plugin breakage (more than just
> re-compile) every time the Geany internals change.
> Perhaps the call should go out to plugin developers, in general do
> they mind the disruption in return for more access to Geany
Personally, I just want it to be clear what is exposed and what isn't.
Currently since you have to go digging in Geany's header files as well
as the API reference, the line gets blurred. For example these two
members of GeanyApp:
Why aren't these "part of the API"? They are certainly useful, so is it
just a matter of missing Doxygen comments, or is there a reason plugins
shouldn't know about these?
>>>> Another thing that would be really helpful is to add something to the
>>>> doxygen comments like '@since' and to put the plugin API number when
>>>> that function/member/struct became available.
>>> I'm not sure about. The most interesting number is die Geany main
>>> version as you want to build something up to recent Geany version.
>>> However, I do understand your suggestion with API number and IIRC we
>>> had something like this under discussion earlier.
> Providing this information will allow plugin developers to make their
> plugin adapt somewhat to which Geany it is being compiled against.
Yep, for example in GeanPy, I could avoid wrapping certain newer
functions since the last release using cpp macros, so that it could
still compile on older releases. Though I have no idea what API version
number relates to what Geany Relase version number.
> How would you show API and ABI info? IIRC the theory is that ABI
> changes don't require unchanged plugins to be recompiled (for example
> if a structure is extended) but API changes require at least
> recompile. But I am not sure it is working that way though?
I probably don't understand the topic enough, but to me, it would be
cool to say:
PLUGIN_VERSION_CHECK(0, 20, 42)
To mean: "This plugin will only work on the 42nd API change since the
0.20 release or later". And the Doxygen comments for an API function
could look like:
* Does something to foo with bar.
* @since 0.20.42
void baz(int foo, int bar);
Or at least something along these lines, so that it relates to release
version numbers of Geany. Would be great to then get a macro like
#if GEANY_VERSION_CHECK(0, 20, 42)
/* Do nothing on older APIs */
Just some thoughts, I have no idea if it's realistic.
More information about the Devel