X-Git-Url: https://git.draconx.ca/gitweb/gob-dx.git/blobdiff_plain/a611f21fab136f64bbf979bd62b2fc6ecb62933c..refs/tags/v0.91.1:/doc/gob.1.in

diff --git a/doc/gob.1.in b/doc/gob.1.in
index 4268580..9cada9a 100644
--- 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
@@ -89,6 +104,23 @@ For example:
 
 .fi
 
+.SH INCLUDE FILES
+.PP
+Gob will automatically include the class header file at the top of the .c 
+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
 The class header:
@@ -121,9 +153,28 @@ identifier allowed per typename unlike in normal C.  Example:
 
 .fi
 .PP
-The private members are not currently protected from outside use,
-they are just marked by a comment in the header file, this will most likely
-be somehow solved in some future version.
+Public datamembers are accessed normally as members of the object struct.
+Example where 'i' is as above a public data member:
+.nf
+
+  object->i = 1;
+
+.fi
+.PP
+The private data members are defined in a structure which is only available
+inside the .c file.  You must access them using the structure _priv.  Example
+where 'h' is the private data member (as in the above example):
+.nf
+
+  object->_priv->h = NULL;
+
+.fi
+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
@@ -276,6 +327,7 @@ class, you can use the PARENT_HANDLER macro with your arguments.  Example:
           /* some code here */
           PARENT_HANDLER(self, wid);
   }
+
 .fi
 .PP
 Calling methods:
@@ -306,7 +358,7 @@ this method, you can use the GET_NEW macro that is defined for you and that
 will fetch a new object, so a fairly standard new method would look like:
 .nf
 
-  public GtkWidget *
+  public GtkObject *
   new(void) {
 	  GtkObject *ret;
 	  ret = GTK_OBJECT (GET_NEW);
@@ -328,10 +380,6 @@ compile with a C++ compiler.
 
 .SH BUGS
 .PP
-The generated header file is included as the first file in the .c file, no
-matter what. This means that you will have to put things that need to be
-included before that, into an %h{ } section.
-.PP
 Also the lexer does not actually parse the C code, so I'm sure that some corner
 cases or maybe even some not so corner cases of C syntax might confuse gob
 completely.  If you find any, send me the source that makes it go gaga and I'll