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

[Colomban Wendling]

Le 16/08/2011 10:05, Lex Trotman a écrit :
> 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.

+1 here, but I'd be fine to be proven wrong.  But anyway copying the
function signature or any other information that could be automatically
found by Doxygen, GtkDoc or whatever source-comment-and-analysis-based
documentation tool is not an option.  This kind of thing would be the
easiest way to have documentation and code out-of-sync.

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

That's it.  But it's also true that some things that should probably be
in the plugins docs are missing from it.

>  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 :-)

I guess so, yes.  Though, I don't see why a plugin would like to know
these information.  app->configdir is in the plugin API and makes sense,
but data and doc dir don't makes much sens to me.

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

Well, as you say it's two different things: the plugin developer only
needs the API number (and only cares about the Geany version number to
tell her users), while the user and packager only wants to know the
Geany version needed.

So we probably better provide and easy way to know to which Geany
version corresponds a particular API number (e.g. by having a simple
mapping, quite easy to do BTW) or something, because I don't see any
reason the plugin writer would like to bother about which actual Genay
version is needed on the code side.

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

As said above, I don't see why the Geany version should appear in a
check like this.  The API version is enough to do the check, and having
both simply makes it harder to update the check at a later point if it
happens to be needed.  Or maybe I got it completely wrong?


> This isn't a new problem, does anyone know how other software with
> plugins does it?

Many the applications uses a shared library and simply applies the rules
of shared libraries: don't break things often, and provide compile-time
and run-time checks for your users.


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

Good question.  Though, maybe they inspect plugin's code (used symbols,
used data, etc. -- it's XUL after all) to check it against the available
API?
And each plugin has the information in it, e.g. "from 2.0.* to 5.0.*"


Cheers,
Colomban