[Geany-devel] SF.net SVN: geany:[5875] trunk/src

[Matthew Brush]

On 07/31/11 18:39, Lex Trotman wrote:
> On 1 August 2011 10:51, Matthew Brush<mbrush at codebrainz.ca>  wrote:
>> On 07/31/11 06:35, colombanw at users.sourceforge.net wrote:
>>>
>>> Revision: 5875
>>>            http://geany.svn.sourceforge.net/geany/?rev=5875&view=rev
>>> Author:   colombanw
>>> Date:     2011-07-31 13:35:43 +0000 (Sun, 31 Jul 2011)
>>>
>>> Log Message:
>>> -----------
>>> Add missing documentation for GeanyInterfacePrefs and GeanyToolPrefs
>>>
>>
>> Just a few more that seem to be missing:
>>         GeanyEditorPrefs
>>         GeanyFilePrefs
>>         GeanyBuildInfo
>>         GeanyFilePrefs
>>         GeanyEditorPrefs
>
>
> Hi Matthew,
>
> Warning as I said in previous post much is deliberately not included
> in the API.  Don't go just adding everything.
>
> For example build info was removed from the API by Nick after we had a
> long (and sometimes acrimonious) discussion about how it should be
> exposed.  While I don't agree with him, I understand his decision to
> expose nothing until the argument was resolved.

Ah, that's cool. (I don't know the history here)

But shouldn't those not appear in the API documentation at all rather 
than dead-links?  I recon it would be just removing a few /** here and 
there?

Using the GeanyBuildInfo example, if it's not public, why is it listed 
in the GeanyData documentation[1] at all?  IMHO, in plugindata.h:242, 
the doc-comment '/**< Current build information */' should be replaced 
with '/* Current build information */' or whatever to remove it from the 
generated API docs.  It's either public or not, but having it 
half-documented members/types leading to a dead-link is both confusing 
and annoying (these Python bindings are a *LOT* of typing :)

[1] http://www.geany.org/manual/reference/structGeanyData.html

Cheers,
Matthew Brush