After an evaluation, GNOME has moved from Bugzilla to GitLab. Learn more about GitLab.
No new issues can be reported in GNOME Bugzilla anymore.
To report an issue in a GNOME project, go to GNOME GitLab.
Do not go to GNOME Gitlab for: Bluefish, Doxygen, GnuCash, GStreamer, java-gnome, LDTP, NetworkManager, Tomboy.
Bug 651745 - Switch to _ prefixing rather than G_GNUC_INTERNAL
Switch to _ prefixing rather than G_GNUC_INTERNAL
Status: RESOLVED FIXED
Product: glib
Classification: Platform
Component: general
unspecified
Other All
: Normal normal
: ---
Assigned To: gtkdev
gtkdev
Depends on:
Blocks:
 
 
Reported: 2011-06-02 21:36 UTC by Colin Walters
Modified: 2011-06-07 18:55 UTC
See Also:
GNOME target: ---
GNOME version: ---


Attachments
GBuffer: Switch to _ prefixing rather than G_GNUC_INTERNAL (9.69 KB, patch)
2011-06-02 21:36 UTC, Colin Walters
none Details | Review
gobject: Use _ prefixing in private headers over G_GNUC_INTERNAL in public headers (9.91 KB, patch)
2011-06-02 21:36 UTC, Colin Walters
committed Details | Review
gsettings-mapping: Use _ prefixing in private headers over G_GNUC_INTERNAL (4.90 KB, patch)
2011-06-02 21:36 UTC, Colin Walters
none Details | Review
gvariant-core: Use _ prefixing in private headers over G_GNUC_INTERNAL (13.93 KB, patch)
2011-06-02 21:36 UTC, Colin Walters
none Details | Review
GBuffer: Move header to -private.h (3.07 KB, patch)
2011-06-03 17:19 UTC, Colin Walters
committed Details | Review
glib: generate glib-public-headers.txt file, feed it to gtk-doc (2.71 KB, patch)
2011-06-03 19:01 UTC, Colin Walters
reviewed Details | Review
Generate $module-public-headers.txt file, feed it to gtk-doc (5.96 KB, patch)
2011-06-03 20:34 UTC, Colin Walters
committed Details | Review

Description Colin Walters 2011-06-02 21:36:03 UTC
This helps out gtk-doc and g-ir-scanner, and also makes much clearer
what's private versus public.
Comment 1 Colin Walters 2011-06-02 21:36:04 UTC
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.
Comment 2 Colin Walters 2011-06-02 21:36:07 UTC
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.
Comment 3 Colin Walters 2011-06-02 21:36:09 UTC
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.
Comment 4 Colin Walters 2011-06-02 21:36:12 UTC
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.
Comment 5 Javier Jardón (IRC: jjardon) 2011-06-03 08:51:45 UTC
Maybe is a good idea to move the private functions to private headers, ie, gbufferprivate.h ?
Comment 6 Matthias Clasen 2011-06-03 13:39:40 UTC
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.
Comment 7 Colin Walters 2011-06-03 15:13:58 UTC
(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
Comment 8 Matthias Clasen 2011-06-03 15:18:30 UTC
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
Comment 9 Colin Walters 2011-06-03 15:27:14 UTC
(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?
Comment 10 Matthias Clasen 2011-06-03 16:31:32 UTC
(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 11 Colin Walters 2011-06-03 16:47:41 UTC
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
Comment 12 Colin Walters 2011-06-03 17:19:33 UTC
Created attachment 189171 [details] [review]
GBuffer: Move header to -private.h
Comment 13 Colin Walters 2011-06-03 19:01:48 UTC
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.
Comment 14 Matthias Clasen 2011-06-03 20:05:54 UTC
Review of attachment 189171 [details] [review]:

ok
Comment 15 Matthias Clasen 2011-06-03 20:07:49 UTC
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 ?
Comment 16 Colin Walters 2011-06-03 20:34:30 UTC
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
Comment 17 Matthias Clasen 2011-06-04 01:19:09 UTC
Review of attachment 189183 [details] [review]:

Feel free to commit if it survives make distcheck
Comment 18 Javier Jardón (IRC: jjardon) 2011-06-04 11:56:12 UTC
@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
Comment 19 Colin Walters 2011-06-04 17:20:35 UTC
(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?
Comment 20 Dan Winship 2011-06-04 19:19:29 UTC
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...)
Comment 21 Matthias Clasen 2011-06-05 15:14:01 UTC
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