[Github-comments] [geany] doxygen: various doxygen-related fixes in preparation for gtkdoc generation (302b40e)

[Thomas Martitz]

Am 17.12.2015 um 13:46 schrieb Colomban Wendling:
>
> I agree with @codebrainz <https://github.com/codebrainz> (as I already 
> mentioned earlier).
> Sure, there is a gray area on what's public and private inside 
> publicly accessible structures, as we (currently) don't have any way 
> to enforce privacy here.
>

We do have FooStructPrivate, and use it in quite a few struct types. Now 
there is another way to introduce private fields, and this is quite news 
to me and quite awkward if you're used to the FooStructPrivate convention.

> But we always stated that anything undocumented was /not/ part of the 
> API and could not be relied upon, so although in practice it was 
> possible, we explicitly said we didn't support that.

Yea, only stuff that's documented is officially part of the API. That 
doesn't automatically make everything else strictly private, though. We 
can't just go and change or remove the so-called "private" members so 
because that breaks the ABI even for well-behaving plugins. So these 
"private" members are in fact part of the ABI and in practice public. We 
should simply document the fact and do not allow such grey areas to 
remain grey.

If we really want private fields, that we can change freely, use 
FooStructPrivate. But we also have to accept that, documented or not, 
all public struct members are part of the ABI and subject to concerns 
before changing.


---
Reply to this email directly or view it on GitHub:
https://github.com/geany/geany/commit/302b40e9778ff49407902f3ef9f272ed202f4547#commitcomment-15068227
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.geany.org/pipermail/github-comments/attachments/20151218/1607d410/attachment.html>