Welcome to the Java Programming Forums


The professional, friendly Java community. 21,500 members and growing!


The Java Programming Forums are a community of Java programmers from all around the World. Our members have a wide range of skills and they all have one thing in common: A passion to learn and code Java. We invite beginner Java programmers right through to Java professionals to post here and share your knowledge. Become a part of the community, help others, expand your knowledge of Java and enjoy talking with like minded people. Registration is quick and best of all free. We look forward to meeting you.


>> REGISTER NOW TO START POSTING


Members have full access to the forums. Advertisements are removed for registered users.

Results 1 to 5 of 5

Thread: Javadoc questions

  1. #1
    Junior Member
    Join Date
    Jan 2013
    Posts
    22
    Thanks
    5
    Thanked 1 Time in 1 Post

    Default 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 );
        }
    }


  2. #2
    Super Moderator Norm's Avatar
    Join Date
    May 2010
    Location
    Eastern Florida
    Posts
    21,917
    Thanks
    55
    Thanked 2,352 Times in 2,323 Posts

    Default Re: Javadoc questions

    If you don't understand my answer, don't ignore it, ask a question.

  3. #3
    Junior Member
    Join Date
    Jan 2013
    Posts
    22
    Thanks
    5
    Thanked 1 Time in 1 Post

    Default Re: Javadoc questions

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

  4. #4
    Super Moderator Norm's Avatar
    Join Date
    May 2010
    Location
    Eastern Florida
    Posts
    21,917
    Thanks
    55
    Thanked 2,352 Times in 2,323 Posts

    Default Re: Javadoc questions

    What does the javadoc program create from your comments?
    If you don't understand my answer, don't ignore it, ask a question.

  5. #5
    Super Moderator pbrockway2's Avatar
    Join Date
    Jan 2012
    Posts
    979
    Thanks
    7
    Thanked 206 Times in 182 Posts

    Default Re: Javadoc questions

    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...

  6. The Following User Says Thank You to pbrockway2 For This Useful Post:

    bdennin (January 31st, 2013)

Similar Threads

  1. How do you feel about my javadoc comments?
    By bdennin in forum Java Theory & Questions
    Replies: 1
    Last Post: January 31st, 2013, 08:38 PM
  2. need help finding code in javadoc
    By lf2killer in forum Java Theory & Questions
    Replies: 3
    Last Post: October 13th, 2012, 09:52 AM
  3. Creating a javadoc help please.
    By jerryg in forum What's Wrong With My Code?
    Replies: 6
    Last Post: March 8th, 2012, 10:10 AM
  4. Double always == 0! And a Javadoc issue! (Using NetBeans)
    By CameronFaust in forum What's Wrong With My Code?
    Replies: 2
    Last Post: August 11th, 2011, 01:22 AM
  5. How do you generate javadoc?
    By javapenguin in forum Java IDEs
    Replies: 15
    Last Post: November 27th, 2010, 09:12 PM