[Geany-devel] Adding a list of filetypes into devel documentation?

[Matthew Brush]

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?

Sure thing:
http://codebrainz.github.com/geany-sphinx/

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.

+1

> Perhaps the call should go out to plugin developers, in general do
> they mind the disruption in return for more access to Geany
> capabilities?
>

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:

	geany_data->app->datadir
	geany_data->app->docdir

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 
GLib/GTK has:

	#if GEANY_VERSION_CHECK(0, 20, 42)
		baz(1, 2);
	#else
		/* Do nothing on older APIs */
	#endif

Just some thoughts, I have no idea if it's realistic.

Cheers,
Matthew Brush