Release 0.91.1

[gob-dx.git] / doc / gob.1.in

diff --git a/doc/gob.1.in b/doc/gob.1.in
index f18490dd83ef30a14c821685804719784ee8275e..9cada9a7ecafcee4cc130cf7afda4e12839c766a 100644 (file)
--- a/doc/gob.1.in
+++ b/doc/gob.1.in
@@ -41,7 +41,17 @@ Generate C++ code.
 Don't touch the generated header file unless it really changed, this avoids
 spurious rebuilds, but can confuse some make systems (automake in particular),
 so it is not enabled by default.
-
+.TP
+.B --always-private-header
+Always create a \fB<basename>-private.h\fR file, even if it would be empty.
+Otherwise, it is only created when there are private data members in the class.
+This option implicitly negates --no-private-header
+.TP
+.B --no-private-header
+Never create a private header file.  If we use any private datamembers,
+define the private data structure at the point in the .c source where
+the class definition begins.  This option implicitly negates
+--always-private-header
 
 .SH TYPENAMES
 .PP
@@ -58,8 +68,13 @@ types.
 .PP
 The filenames are created from the typename.  The words are
 separated by '-' and all in lower case.  For example for an object named
-"Gtk:New:Button", the files are gtk-new-button.c and gtk-new-button.h.
-The header file is created to be human readable and to be used as a
+"Gtk:New:Button", the files are \fBgtk-new-button.c\fR and
+\fBgtk-new-button.h\fR.
+If you are using C++ mode, the output .c file will in fact be a .cc file.
+If you have any private data members, a private header file will also
+be created, called \fB<basename>-private.h\fR (for the example above it
+would be gtk-new-button-private.h).
+The public header file is created to be human readable and to be used as a
 reference to the object.  The .c source file is not created as a human
 readable source and is littered with #line statements, which make the
 compiler attempt to point you to the right line in your .gob file in
@@ -96,6 +111,15 @@ source file.  If you wish to include it somewhere else, put the include
 into some %{ %} section above the class definition, and gob will not include
 it automatically.  This way you can avoid circular includes and control
 where in the file do you want to include the header.
+.PP
+If you made any data members private, gob will also create a source file
+that will be called \fB<basename>-private.h\fR.  Same rule as above applies
+for this just as it does for the regular header file.  If you do explicitly
+include the regular header file, you should always include this private
+header file below it.  That is, if you use any private data members.  If you
+don't, the private header file automatically includes the public header file,
+and thus the public header file will be indirectly included at the very top
+of the file.
 
 .SH MAKING A NEW CLASS
 .PP
@@ -145,9 +169,12 @@ where 'h' is the private data member (as in the above example):
   object->_priv->h = NULL;
 
 .fi
-Note that the _priv structure is only accessible to C code blocks below or
-inside the class definition in the .gob file.  If you use it above, you will
-get a 'dereferencing incomplete pointer type' error from the C compiler.
+Note that the _priv structure is defined in the \fB<basename>-private.h\fR.
+This file is automatically included if you don't include it yourself.  You
+should always explicitly include it if you explicitly also include the main
+header file.  In case you use the \fB--no-private-header\fR option, no
+private header file is created and you can only access the _priv pointer
+below the class definition in the .gob file.
 .PP
 The third type is an argument type.  It is a named datamember which
 is one of the features of the GTK+ object system.  You need to define a get