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

[Lex Trotman]

On 16 August 2011 12:19, Matthew Brush <mbrush at codebrainz.ca> wrote:
> 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/

Nice, so I read the Sphinx doco (havn't looked at it for a while) but
IIUC either you have to repeat the C declarations that appear in the
documentation or use doxygen and breathe to extract it.

1. The repeat option is unacceptable.

2. Although the output is nice I don't see enough is gained by the
second option to justify having to use two tools (sphinx and breathe)
on top of the current one (doxygen).

So at the moment I don't see that this justifies the change.

>
> 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.

Correct me if I'm wrong but I understood that if it isn't in the
doxygen API docs it should not be used in plugins, even if the
compiler says its accessible.  If its not documented there is no
requirement for the declaration or semantics to remain the same or for
there to be any indication when it changes.


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

Probably no-one asked for them, as I said before the approach to date
has been to not proactively add things to the API.

They would be part of the discussion above of making more available :-)

[...]
> 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.

ditto

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

As Frank points out in another post I've got this backwards :-S

The point is that if the ABI number must match exactly but API greater
than what your plugin needs is ok.

>
[...]
> 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:
>

I agree that the requirement should be re-cast to be in line with
release numbers, whilst the simple incrementing integer is good for
SVN builders to select the exact version, users and packagers want to
know which release version is required.

>        #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.

This isn't a new problem, does anyone know how other software with
plugins does it?  Firefox for example raises a dialog each time its
upgraded saying its checking plugins and it disables any that won't
work.  How does it make the decision?

Cheers
Lex