X-Git-Url: https://git.draconx.ca/gitweb/gob-dx.git/blobdiff_plain/072bb12e618b26cce359784aa56f9a2b70e1ce52..c9914e54f16c3315d47040f4cca2d3788228c504:/doc/gob.1.in?ds=sidebyside

diff --git a/doc/gob.1.in b/doc/gob.1.in
index 9e1ce35..7d0c285 100644
--- 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
@@ -735,13 +739,17 @@ will fetch a new object, so a fairly standard new method would look like:
 
   public GtkObject *
   new(void) {
-	  GtkObject *ret;
-	  ret = GTK_OBJECT (GET_NEW);
-	  return ret;
+	  GtkObject *ret = GET_NEW;
+	  return GTK_OBJECT (ret);
   }
 
 .fi
 .PP
+You should not a subtle peculiarity of the GTK+ object system here.  If there is any
+code inside the GTK_OBJECT macro argument, it will get executed multiple times.  This
+means that things such as GTK_OBJECT(GET_NEW) would actually create 4 objects, leaking
+3 of them.  A good rule is to be careful with all macros.
+.PP
 Self alias casts:
 .PP
 There are some standard casts defined for you.  Instead of using the full
@@ -931,6 +939,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