Release 1.0.2

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

diff --git a/doc/gob.1.in b/doc/gob.1.in
index 9e1ce35bf0c19b3981d67c523aa00ff2d7351dc9..01d66cdbf1cb1adb5d3d08cfdb7102cb85321edd 100644 (file)
--- a/doc/gob.1.in
+++ b/doc/gob.1.in
@@ -77,6 +77,11 @@ and SELF_CLASS macros.
 .TP
 .B --no-kill-underscores
 Do not remove the initial underscore from method names.
+.TP
+.B --always-private-struct
+Always include the private pointer in the public header file.  This is useful for
+files which are part of a library and you want to reserve the right to add some
+private data members without breaking binary compatibility.
 
 .SH TYPENAMES
 .PP
@@ -439,7 +444,7 @@ is just like
   private char * foo;
   argument POINTER (type char *) foo
   get {
-        ARG = self->_priv->foo;
+        ARG = g_strdup(self->_priv->foo);
   } set {
        g_free(self->_priv->foo);
         self->_priv->foo = g_strdup(ARG);
@@ -472,10 +477,9 @@ is just like
 .PP
 As you see it will handle NULLs correctly (for the string, g_free and g_strdup
 handle NULLs).  And it will also handle private, protected and public members.
-Also you should notice that when the get is used, only a pointer is always
-returned for both objectlink and strinklink.  So you should treat the returned
-value with care and never free it (and notice that it will only be around
-until you set the argument to something else or destroy the object).
+For objectlink, just a pointer is returned on get, if you wish to keep it around,
+you should call gtk_object_ref on it.  For stringlink, get makes a copy of
+the string which you should free after use.  This is the behaviour since 1.0.2.
 .PP
 Methods:
 .PP
@@ -931,6 +935,23 @@ include the generated .c and .h files into BUILT_SOURCES variable.  You
 have to include both the .gob and the .c and .h files in the SOURCES for your
 program.
 
+.SH DEBUGGING
+.PP
+GOB does several things to make debugging the code easier.  First it adds
+preprocessor commands into the output c file that point to the correct places
+in your .gob input file.  However sometimes there might be some bigger
+confusion and this is just not helpful.  In this case you will probably want
+to have gcc point you directly at the generated files.  For this use
+the --no-lines command line option.  You should also note that these commands
+are not generated for the public header file at all.  If there is an error which
+points you to the public header file, make sure you fix this error in the .gob
+file, otherwise your changes will not have any effect after gob recompiles the
+sources again.
+.PP
+Sometimes you might want to know which method you are in for some debugging
+output.  GOB will define __GOB_FUNCTION__ macro, which is just a string constant
+with a pretty name of the method.
+
 .SH BUGS
 .PP
 The lexer does not actually parse the C code, so I'm sure that some corner