Release 0.92.4

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

diff --git a/doc/gob.1.in b/doc/gob.1.in
index 40916fd87335d3b33ccdc8456dad984225724bb5..6717d3e2a89cbeace89fe7367c710e33217d0f1a 100644 (file)
--- a/doc/gob.1.in
+++ b/doc/gob.1.in
@@ -10,9 +10,9 @@
 GOB \- The GTK+ Object Builder
 .SH SYNOPSIS
 .PP
-.B gob [-?] [-h] [--help] [--version] [-w] [--exit-on-warn]
-[--no-exit-on-warn] [--for-cpp] [--no-gnu] [--always-private-header]
-[--no-private-header] [--no-touch-headers] file
+.B gob
+[ option ] ...
+file
 .SH DESCRIPTION
 .PP
 GTK+ Object Builder is a simple preprocessor for easily creating
@@ -69,6 +69,11 @@ Never create a private header file.  If we use any private data members,
 define the private data structure at the point in the .c source where
 the class definition begins.  This option implicitly negates
 --always-private-header
+.TP
+.B -n
+.TP
+.B --no-write
+Do not write any output files, just check syntax of the input file.
 
 .SH TYPENAMES
 .PP
@@ -109,9 +114,16 @@ go into the public header file.  You can also put it in the 'privateheader'
 section (abbreviated 'ph') which will make the code go into the private
 header file.  Sometimes you want some code (other includes) to appear before
 the extern "C" and the protecting define.  To do this you can put them
-into the 'headertop' (or 'ht') section.  For example:
+into the 'headertop' (or 'ht') section.  You may wish to include code or
+comments in all the files, which you can do by putting them into the 'all'
+(or 'a') section.  Similarly, code you wish to appear at the top of all
+files go in the 'alltop' (or 'at') section.  For example:
 .nf
 
+  %alltop{
+  /* this will be on top of all output files */
+  %}
+
   %headertop{
   /* this will be on top of the public header */
   %}
@@ -125,6 +137,10 @@ into the 'headertop' (or 'ht') section.  For example:
   void somefunc(int i);
   %}
 
+  %a{
+  /* will be included in all files */
+  %}
+
   %{
   /* will be included in the C file */
   void somefunc(int i)
@@ -357,10 +373,10 @@ it's init or class_init.
 For example:
 .nf
 
-  init(object) {
+  init(self) {
           /* initialize the object here */
-          object->a = 9;
-          object->b = 9;
+          self->a = 9;
+          self->b = 9;
   }
 
   class_init(class) {
@@ -428,6 +444,11 @@ by using "protected" instead of "private".
 If you don't define a "first" or a "last", the default will be taken as
 "last".
 .PP
+You can also add additional flags.  You do this just like with the argument
+flags, although this is probably very rare.  These are the GTK_RUN_* flags,
+and you can add them without the GTK_RUN_ prefix into a parenthesis, just
+after the "signal" keyword.  By default all public signals are GTK_RUN_ACTION.
+.PP
 Override methods:
 .PP
 If you need to override some method (a signal or a virtual method
@@ -489,6 +510,13 @@ will fetch a new object, so a fairly standard new method would look like:
 
 .fi
 .PP
+Casts:
+.PP
+There are some standard casts defined for you.  Instead of using the full
+macros inside the .c file, you can use SELF, IS_SELF and SELF_CLASS.  Using
+these makes it easier to for example change classnames around.  There is
+however no self type, so if you're declaring a pointer to your object, you
+still have to use the full type.
 
 .SH DEALING WITH DIFFERENT GOB VERSIONS
 .PP
@@ -548,6 +576,42 @@ argument lists and virtual and signal method names as it might confuse the
 PARENT_HANDLER macro.  In fact avoiding all names with three underscores is
 the best policy when working with gob.
 
+.SH USING GTK-DOC STYLE INLINE DOCUMENTATION
+.PP
+If you want to use gtk-doc style inline documentation for your objects, you
+can do one of two things.  First, you could include the inline documentation
+comments in your %{ %} section which will then be put verbatim into the
+output source file.  This is the way you should use for functions you define
+outside of the class.
+.PP
+For class methods, you should use a gtk+ style comment, however it can be
+indented any number of tabs or spaces and you can use the short method name
+without the type prefix.  Gob will automatically try to extract these and
+translate to full names and put them in the output source file.  An example
+would be:
+.fi
+
+  class Gtk:Button:Example from Gtk:Button {
+          /**
+           * new:
+           *
+           * Makes a new #GtkButtonExample widget
+           *
+           * Returns: a new widget
+           **/
+          public
+          GtkWidget *
+          new(void)
+          {
+                  return GTK_WIDGET(GET_NEW);
+          }
+  } 
+
+.fi
+If the function you are documenting is a signal or a virtual then it will
+be documentating the wrapper that starts that virtual function or emits
+that signal.
+
 .SH DEALING WITH CIRCULAR HEADERS
 .PP
 Sometimes you may need to use an object of type MyObjectA in the MyObjectB