On 07/31/11 06:35, colombanw@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
There's probably more, I will report as I sift through the API docs writing the Python bindings.
Cheers, Matthew Brush
On 1 August 2011 10:51, Matthew Brush mbrush@codebrainz.ca wrote:
On 07/31/11 06:35, colombanw@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.
Cheers Lex
On 07/31/11 18:39, Lex Trotman wrote:
On 1 August 2011 10:51, Matthew Brushmbrush@codebrainz.ca wrote:
On 07/31/11 06:35, colombanw@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
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