GNOME Bugzilla – Bug 324880
gtk-doc treats only GObject struct as private but not GObjectClass structs
Last modified: 2018-05-22 13:00:44 UTC
As default gtk-doc treats members of GObject classes as private, but treats members in GObjectClass structs as public by default. This is bad as in the following example, gtk-doc will warn about undocumented 'parent' field in BtSongClass but not in BtSong. Suggested behaviour is to treat members in both as private by default. struct _BtSong { GObject parent; /*< private >*/ BtSongPrivate *priv; }; struct _BtSongClass { GObjectClass parent; /*< private >*/ };
Created attachment 56331 [details] [review] also treat members in class structs as private fixes a few comments (GtkObject -> GObject) implements the consistent struct handling
It probably would have been better to be consistent as you say. But I'm not sure we should change this now, as it may affect existing documentation (i.e. lots of Class documentation may suddenly disappear).
I don't know a lot of *class* docs really. And all the need to do is to put a /*< public > */ line into the source, where appropriate. I can try to check if this way docs are lost and warn then. Its better to explicitly mark private/public parts anyway. Would that be good then?
Yes, I think marking everything explicitly is the best way to go. Even if we check all GTK+ & GNOME docs, there may be other people using gtk-doc who this would affect.
good news. gtk-doc already catches this: WARNING: Field described in source code comment block but does not exist - STRUCT: GstBinClass Field: parent_class.
Created attachment 109744 [details] [review] also treat members in class structs as private Committed the comment changes 8that get rid of mentioning GTK). The patch probably needs a different approach. If one conditionally disables some types in the library, they are not treated as object anymore and thus one also get errors here.
We can add a --private-class-scope switch to gtkdoc-mkdb. That allows projects to migrate. On older gtk-doc it would still build with warnings. See extra discussion in Bug #652746.
-- GitLab Migration Automatic Message -- This bug has been migrated to GNOME's GitLab instance and has been closed from further activity. You can subscribe and participate further through the new bug through this link to our GitLab instance: https://gitlab.gnome.org/GNOME/gtk-doc/issues/3.