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 324880 - gtk-doc treats only GObject struct as private but not GObjectClass structs
gtk-doc treats only GObject struct as private but not GObjectClass structs
Status: RESOLVED OBSOLETE
Product: gtk-doc
Classification: Platform
Component: general
unspecified
Other Linux
: Normal normal
: ---
Assigned To: Stefan Sauer (gstreamer, gtkdoc dev)
gtk-doc maintainers
Depends on:
Blocks:
 
 
Reported: 2005-12-23 14:42 UTC by Stefan Sauer (gstreamer, gtkdoc dev)
Modified: 2018-05-22 13:00 UTC
See Also:
GNOME target: ---
GNOME version: ---


Attachments
also treat members in class structs as private (1.78 KB, patch)
2005-12-23 14:43 UTC, Stefan Sauer (gstreamer, gtkdoc dev)
none Details | Review
also treat members in class structs as private (488 bytes, patch)
2008-04-23 07:59 UTC, Stefan Sauer (gstreamer, gtkdoc dev)
none Details | Review

Description Stefan Sauer (gstreamer, gtkdoc dev) 2005-12-23 14:42:11 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 >*/
};
Comment 1 Stefan Sauer (gstreamer, gtkdoc dev) 2005-12-23 14:43:48 UTC
Created attachment 56331 [details] [review]
also treat members in class structs as private

fixes a few comments (GtkObject -> GObject)
implements the consistent struct handling
Comment 2 Damon Chaplin 2006-01-09 16:04:11 UTC
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).

Comment 3 Stefan Sauer (gstreamer, gtkdoc dev) 2006-01-09 16:26:33 UTC
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?
Comment 4 Damon Chaplin 2006-01-09 17:04:15 UTC
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.
Comment 5 Stefan Sauer (gstreamer, gtkdoc dev) 2006-01-12 21:52:22 UTC
good news. gtk-doc already catches this:
WARNING: Field described in source code comment block but does not exist -
         STRUCT: GstBinClass Field: parent_class.
Comment 6 Stefan Sauer (gstreamer, gtkdoc dev) 2008-04-23 07:59:41 UTC
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.
Comment 7 Stefan Sauer (gstreamer, gtkdoc dev) 2011-09-06 13:09:57 UTC
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.
Comment 8 GNOME Infrastructure Team 2018-05-22 13:00:44 UTC
-- 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.