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

[Lex Trotman]

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

I must add that the acrimony is the sort that could easily be fixed if
we could have sat down with a beer and talked about it rather than
plough through the misunderstandings of e-communications.  But flying
24 hours for that purpose isn't going to happen.

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

I am only aware of the history relating to the build system interface
but the principle of not exposing things that may restrict internal
implementation and present a maintenance headache was clearly
presented.  And it seems to have been applied elsewhere as well, hence
my caution.

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

Oops. I was using build info as a generic term, I forgot that there
was a structure of that name :-)

IIRC the buildinfo structure is an example of the lock-in that happens
once some API is exposed. Since it was exposed in the API prior to the
build-system re-write it wasn't removed, someone may be depending on
it.  If it was to be removed there would need to be a period of
deprecation first.

But it sounds like in the rush to limit the build system exposure
there may have been some unintended side effects.  It would be best to
check what was exposed in say 0.18.

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

Well you could leave out anything you are not 100% sure about for now
and get more guidance when NH summer is over :-)

Cheers
Lex