Documentation

Ok, guys, dreaded documentation. Please try to remember to at least get the javadocs done. I’m following the standard:



documentation of a class



/**

  • <code>CLASS_NAME</code> does this blah blah blah.
  • @author YOUR_NAME
  • @version $Id$

    */



    the $Id$ lets CVS plug in the version number.



    documentation of a method



    /**
  • <code>METHOD_NAME</code> does this blah blah blah.
  • @param ANY_PARAMS
  • @return ANY_RETURN_VALUES
  • @throws ANY_EXCEPTION

    */



    Each version, the javadocs are made public, so it will help any users a great deal if they can see what specific methods/classes do.



    Thanks.

In case anyone is interested, here is the official guide to writing javadoc comments. It’s … rather comprehensive, to say the least.



The only point of interest to note is “Method descriptions begin with a verb phrase”. I’ll side with them on this and suggest we should perhaps document methods like this. To use their example:

Gets the label of this button. (good)

This method gets the label of this button. (not so good)



Eh, just an idea. What do you think?

That is fine, you can leave off the <code>METHOD_NAME</code> or <code>CLASS_NAME</code> if you like. I’m more concerned about well documented code. If everyone prefers to leave off the <code></code> I’ll change to that style (although it may take me awhile to convert the existing documentation).

I’d perhaps suggest a compromise:

/**

  • <code>AMethod</code> performs some action or other.
  • @param n number of things to do

    */



    At least this way, the existing documentation need not be altered.

Oh, hehe, that’s what I have been doing. I guess my first example didn’t really clearly show that. :slight_smile:

Ah. Well then, at least we agree. :stuck_out_tongue:

Mark, what do you think about posting your eclipse ‘code and comment’ templates? Or, maybe better, adding them to CVS.



Probably not everyone is using eclipse, but the templates could still be used as a reference.



Gregg

I’ll post them to CVS if you’d like. However, I don’t really know which file contains the template information. Do you happen to know? Otherwise, I’ll just post what I have set up on these boards.

I’ll post what I have here and maybe Eric can add it to his Eclipse tutorial.



Under Window->Preferences: Java -> Code Generation:



Code and Comments tab

Constructors

/**

  • ${tags}

    */



    Types

    /**
  • <code>${type_name}</code>
  • @author ${user}
  • @version

    */



    NOTE: You’ll have to add $Id$ to the version. If someone can figure out how to have Eclipse add this without it freaking out about the $ signs let me know.



    Methods

    /**
  • <code>${enclosing_method}</code>
  • ${tags}

    /



    Overridding methods

    /
    <code>${enclosing_method}</code>
  • ${tags}
  • ${see_to_overridden}

    /



    New Java Files

    /

  • Copyright © 2003, jMonkeyEngine - Mojo Monkey Coding
  • All rights reserved.

    *
  • Redistribution and use in source and binary forms, with or without
  • modification, are permitted provided that the following conditions are met:

    *
  • Redistributions of source code must retain the above copyright notice, this
  • list of conditions and the following disclaimer.

    *
  • Redistributions in binary form must reproduce the above copyright notice,
  • this list of conditions and the following disclaimer in the documentation
  • and/or other materials provided with the distribution.

    *
  • Neither the name of the Mojo Monkey Coding, jME, jMonkey Engine, nor the
  • names of its contributors may be used to endorse or promote products derived
  • from this software without specific prior written permission.

    *
  • THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
  • AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  • IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  • ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
  • LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  • CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  • SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  • INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  • CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  • ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  • POSSIBILITY OF SUCH DAMAGE.

    *

    */

    ${package_declaration}



    ${typecomment}

    ${type_declaration}

The tutorial has been updated. FYI, to use the $ symbol, you have to escape by typing $$. Oh, and would you mind hosting that templates file? I’m not certain how long the current location will last, and we can’t afford the bandwidth to toss it on my school’s server.



[size=10px]Edit: awful spelling[/size]

Ok, I put it on the downloads page. Under Utils.