GNOME Bugzilla – Bug 651745
Switch to _ prefixing rather than G_GNUC_INTERNAL
Last modified: 2011-06-07 18:55:28 UTC
This helps out gtk-doc and g-ir-scanner, and also makes much clearer what's private versus public.
Created attachment 189126 [details] [review] GBuffer: Switch to _ prefixing rather than G_GNUC_INTERNAL The _ makes extremely clear that this is not public API, both from the header and when looking at a call. Also, g-ir-scanner doesn't grok it currently, so it's best if we avoid it.
Created attachment 189127 [details] [review] gobject: Use _ prefixing in private headers over G_GNUC_INTERNAL in public headers This helps out gtk-doc and g-ir-scanner, and also makes much clearer what's private versus public.
Created attachment 189128 [details] [review] gsettings-mapping: Use _ prefixing in private headers over G_GNUC_INTERNAL This helps out gtk-doc and g-ir-scanner, and also makes much clearer what's private versus public.
Created attachment 189129 [details] [review] gvariant-core: Use _ prefixing in private headers over G_GNUC_INTERNAL This helps out gtk-doc and g-ir-scanner, and also makes much clearer what's private versus public.
Maybe is a good idea to move the private functions to private headers, ie, gbufferprivate.h ?
Can I say that I find this yet another intrusive change forced upon us by insufficient parsers in those mentioned projects ? I would rather go for private headers, in particular for things like gbuffer where there's a certain chance that the api might become nonprivate at some point.
(In reply to comment #6) > Can I say that I find this yet another intrusive change forced upon us by > insufficient parsers in those mentioned projects ? Of course, though honestly I don't see it as that intrusive. But yes, in reality, GLib has at least 4 different programs "parsing" its source code (for varying levels of "parse"), in descending order of intelligence: gcc, g-ir-scanner, gtk-doc, glib-mkenums. That's the world we live in (for now, work is slowly happening to rebase gtk-doc on g-ir-scanner); it'd be helpful if not every change was met with instant resistance, but negotiation and consideration. > I would rather go for private headers, in particular for things like gbuffer > where there's a certain chance that the api might become nonprivate at some > point. By private headers, do you mean "header files ending in -private.h"? Personally I really like the _ prefixing for private symbols, though it is more annoying for structure definitions. So...how about this then as a rule: For functions which are never planned to be public: * Put them in a header ending in -private.h, and prefix functions with _ For structures and functions which *may* be public: * Have their header file end in -private.h
not sure about demanding the - in the header name. in gtk none of the private headers have that. But they all end in private.h
(In reply to comment #8) > not sure about demanding the - in the header name. in gtk none of the private > headers have that. But they all end in private.h I wouldn't demand it, I just think it's somewhat better. But so - from this discussion then: Can we put http://bugzilla-attachments.gnome.org/attachment.cgi?id=189127 in now? Then I can rework the other patches to just rename the header files to -private.h?
(In reply to comment #9) > > But so - from this discussion then: > > Can we put http://bugzilla-attachments.gnome.org/attachment.cgi?id=189127 in > now? Certainly. Go for it
Comment on attachment 189127 [details] [review] gobject: Use _ prefixing in private headers over G_GNUC_INTERNAL in public headers Attachment 189127 [details] pushed as 3bd3067 - gobject: Use _ prefixing in private headers over G_GNUC_INTERNAL in public headers
Created attachment 189171 [details] [review] GBuffer: Move header to -private.h
Created attachment 189177 [details] [review] glib: generate glib-public-headers.txt file, feed it to gtk-doc Rather than having the gtk-doc build machinery have a list of header files to exclude, change the GLib build to dump a list of public header files generated from the maintained glib/Makefile.am.
Review of attachment 189171 [details] [review]: ok
Review of attachment 189177 [details] [review]: ::: glib/Makefile.am @@ +295,3 @@ + +all-local: glib-public-headers.txt + I assume that file should be added to some clean file list ? Should it go into EXTRA_DIST too ?
Created attachment 189183 [details] [review] Generate $module-public-headers.txt file, feed it to gtk-doc Do it for gobject/ and gio/ too, add CLEANFILES
Review of attachment 189183 [details] [review]: Feel free to commit if it survives make distcheck
@Colin: could you change the *-private.h to *private.h?, ie, gbufferprivate.h instead gbuffer-private.h? It's what we are using until now in gtk and glib
(In reply to comment #18) > @Colin: could you change the *-private.h to *private.h?, ie, gbufferprivate.h > instead gbuffer-private.h? It's what we are using until now in gtk and glib I sort of like the - personally...but i'm not wedded to it. Anyone else care?
I like hyphens in filenames in my code too, but glib and gtk don't use them. (Well, except for the parts written by people who didn't notice that...)
I don't have a strong preference. My main point was that whatever automatic skipping mechanism you built into goi or gtk-doc should skip fooprivate.h as well as bar-private.h