Thread: Javadoc questions

My teacher covered javadoc for less than 5 seconds and I've never done it. Would anyone mind looking at this to see if I did it okay? I'm not sure really what I'm exactly supposed to say for details about integers, or where exactly it's needed.

package gps;
import java.util.Random;
 
/**
 * @author Jimbob
 * @version 1.0
 */
public class GPS
{
    /**
     * The name assigned to construct
     */
    private String name;
    /**
     *  Two part double value assigned to construct
     */
    private GpsCoordinates position;
    Random v1 = new Random();
 
    /**
     * Constructs a GPS from a GpsCoordinate and a string value.
     * @param n String name of GPS
     * @param pos the (x,y) value of GPS
     */
    public GPS ( String n, GpsCoordinates pos )
    {
        name = n;
        position = pos;
    }
    /*
     * Adds a random value between -2.5 and 2.5 to position
     */
    public void updatePosition()
    {
        position.setLatitude( position.getLatitude() - 2.5 + v1.nextInt(6) );
        position.setLongitude( position.getLongitude() - 2.5 + v1.nextInt(6) );
    }
 
    @Override
    /*
     * Converts GPS n to a string value
     * @return string value of GPS n 
     */
    public String toString()
    {
        return String.format( "%s: %s", name, position );
    }
}
/*
 * To change this template, choose Tools | Templates
 * and open the template in the editor.
 */
 
package gps;
 
/**
 * @author Jimbob
 * @version 1.0
 */
public class GpsApp
{
    public static void main( String[] args )
    {
        GpsCoordinates saltLakeCity = new GpsCoordinates( 40.760671, -111.891122 );
        System.out.printf( "Gps coordinates of SLC: %s%n%n", saltLakeCity );
        GPS SLC = new GPS( "Garmin", saltLakeCity );
        System.out.printf( "myGps: %s%n%n", SLC );
        SLC.updatePosition();
        System.out.printf( "position update1:  %s%n", saltLakeCity );
        SLC.updatePosition();
        System.out.printf( "position update2:  %s%n", saltLakeCity );
        SLC.updatePosition();
        System.out.printf( "position update3:  %s%n", saltLakeCity );
    }
}

yes , I just wanted to see what someone thought about my comments, if it looked right, or if there was anything they would critique.

It looks good to me - and better than the documentation you usually see on public forums!

It would be a good idea to add a comment for GPS, what is it. It's a named location and the docs should say that. Avoid implementation details, so name could be described as /** The name of the location.*/ and location as /** The coords of the location.*/. In other words we don't need to be told that thecoords consist of a coule of doubles, or that the name will be assigned...

Consider "self documentation" - NamedLocation is a better name for the class than GPS.

Personally I don't bother with "param" if it abundantly clear from the rest of the documentation. I'm partial to "given" in this respect and would settle for

    /** Constructs a GPS with a given name and coords. */
public GPS(String name, GpsCoordinates coords) {
    this.name = name;
    location = coords;
}

(my brace placement like indenting the javadoc comments is ideosyncratic. There are no rules... Other than those imposed by your boss or teacher...)

Consider documenting main in the driver. This can be handy as a "reminder to self" about how the thing is supposed to be run.

---

As a side point: don't be afraid of posting javadocced code on a forum like this. Noone can (reasonably) begrudge the bandwidth if the comments are to the piunt. And they go a long, long way in communicating how you are thinking and what you intend.

--- Update ---

Sorry for the typos ;(. Using a phone. Over a liquid lunch.

Listen to Norm - he's the real thing: I'm just an amateur who likes to know 6 monthes later what I meant 6 monthes before...