[gtk-doc] help: give better guidance on writing api-docs.

[Stefan Kost <stefkost src gnome org>]

commit 90e0dc2c536baa70649e3d49df5cd46f142927e9
Author: Stefan Kost <ensonic users sf net>
Date:   Tue Apr 5 10:08:35 2011 +0300

    help: give better guidance on writing api-docs.

 help/manual/C/gtk-doc-manual.xml |   20 ++++++++++++++++++++
 1 files changed, 20 insertions(+), 0 deletions(-)
---
diff --git a/help/manual/C/gtk-doc-manual.xml b/help/manual/C/gtk-doc-manual.xml
index a752ff2..362495d 100644
--- a/help/manual/C/gtk-doc-manual.xml
+++ b/help/manual/C/gtk-doc-manual.xml
@@ -734,6 +734,26 @@ gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html
         (blank-asterisk-blank-blank).
       </para>
 
+      <tip>
+        <para>
+          When documenting code, describe two apsects:
+          <itemizedlist>
+             <listitem>
+               <para>
+                 What it is: The name for a class or function can sometimes
+                 be misleading for people coming from a different background.
+                </para>
+             </listitem>
+             <listitem>
+               <para>
+                 What it does: Tell about common uses. Put it in releation
+                 with the other API.
+               </para>
+             </listitem>
+           </itemizedlist>
+        </para>
+      </tip>
+
       <para>
         One advantage of hyper-text over plain-text is the ability to have links
         in the document. Writing the correct markup for a link can be tedious