[ff-cvs] fenfire/docs newbie-dev-faq.rst

[Matti Katila]

CVSROOT:        /cvsroot/fenfire
Module name:    fenfire
Branch:         
Changes by:     Matti Katila <address@hidden>   03/08/29 04:02:58

Modified files:
        docs           : newbie-dev-faq.rst 

Log message:
        writing down the document rules

CVSWeb URLs:
http://savannah.gnu.org/cgi-bin/viewcvs/fenfire/fenfire/docs/newbie-dev-faq.rst.diff?tr1=1.3&tr2=1.4&r1=text&r2=text

Patches:
Index: fenfire/docs/newbie-dev-faq.rst
diff -u fenfire/docs/newbie-dev-faq.rst:1.3 fenfire/docs/newbie-dev-faq.rst:1.4
--- fenfire/docs/newbie-dev-faq.rst:1.3 Fri Jun  6 16:04:32 2003
+++ fenfire/docs/newbie-dev-faq.rst     Fri Aug 29 04:02:58 2003
@@ -3,8 +3,8 @@
 
====================================================================================
 
 :Date:         2002-11-24
-:Revision:     $Revision: 1.3 $
-:Last-Modified:        $Date: 2003/06/06 20:04:32 $
+:Revision:     $Revision: 1.4 $
+:Last-Modified:        $Date: 2003/08/29 08:02:58 $
    
 
 This file is for newbie developers.
@@ -30,7 +30,7 @@
 **Q**: I don't see anything. Just plain black with GL.
 
 **A**: Probably you have some problems with your X drivers etc.
-Update your /usr/X11R6/include/GL/*.
+Update your /usr/X11R6/include/GL/\*.
 
 **A2**: unset LANG
 
@@ -105,6 +105,30 @@
     }
 
 
+Creating well documentated source
+---------------------------------
+
+1. Documenting is part of good source
+
+    - In Fenfire we use java-doc and docxx
+
+2. See the documentation already exists.
+
+    - The most important part of documentation is the first line.
+
+3. Write the documentation
+
+    - Remember the importance of first line in class and method documentation.
+    - Write the truth, don't lie.
+    - If method implements an interface it's javadocced by the interface.
+      So, don't make any worse documentation in implementation, leave it
+      alone or mark it with comment // javadoc in interface etc.
+
+4. Test
+
+    - Ask your friend to look the compiled document and 
+      ask what the class do. If the answer is mess, 
+      your documentation is even worse mess.
 
 Slang
 =====