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

[Tuomas Lukka]

On Fri, Aug 29, 2003 at 04:02:58AM -0400, Matti Katila wrote:
>  
> +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.

Excellent advice!

        Tuomas