[gtk-doc] docs: document more what should be docuemnted and what not

[Stefan Kost <stefkost src gnome org>]

commit 73cded364959ffe54a5bb91f7578fa8c249a0ef9
Author: Stefan Kost <ensonic users sf net>
Date:   Wed Jun 9 18:10:17 2010 +0300

    docs: document more what should be docuemnted and what not
    
    Give better advice for GObject instance and class structs.

 help/manual/C/gtk-doc-manual.xml |   13 +++++++++++++
 1 files changed, 13 insertions(+), 0 deletions(-)
---
diff --git a/help/manual/C/gtk-doc-manual.xml b/help/manual/C/gtk-doc-manual.xml
index 9f939f4..b4df795 100644
--- a/help/manual/C/gtk-doc-manual.xml
+++ b/help/manual/C/gtk-doc-manual.xml
@@ -1114,6 +1114,16 @@ typedef struct _FooWidget {
           you want to hide. Use <code>/*&lt; public &gt;*/</code> for the reverse
           behavirour.
         </para>
+        
+        <para>
+          Struct comment blocks can also be used for GObjects and GObjectClasses.
+          It is usualy a good idea to add a comment blco for a class, if it has
+          vmethods (as this is how they can be documented). For the GObject
+          itself one can use the related section docs, having a separate block
+          for the instance struct would be useful if the instance has public
+          fields. One disadvantage here is that this creates two index entries
+          of the same name (the structure and the section).
+        </para>
 
       </sect2>
 
@@ -1486,6 +1496,9 @@ gtk_arrow_get_type
         If your library contains private types which you don't want to appear in
         the object hierarchy and the list of implemented or required interfaces,
         add them to a Private subsection.
+        Wheter you would place GObject and GObjectClass like structs in public
+        or Standard section depends if they have public entries (variables,
+        vmethods).
       </para>
 
       <para>