• Post Reply Bookmark Topic Watch Topic
  • New Topic
programming forums Java Mobile Certification Databases Caching Books Engineering Micro Controllers OS Languages Paradigms IDEs Build Tools Frameworks Application Servers Open Source This Site Careers Other Pie Elite all forums
this forum made possible by our volunteer staff, including ...
Marshals:
  • Campbell Ritchie
  • Jeanne Boyarsky
  • Ron McLeod
  • Paul Clapham
  • Liutauras Vilda
Sheriffs:
  • paul wheaton
  • Rob Spoor
  • Devaka Cooray
Saloon Keepers:
  • Stephan van Hulst
  • Tim Holloway
  • Carey Brown
  • Frits Walraven
  • Tim Moores
Bartenders:
  • Mikalai Zaikin

assistance with javadoc

 
Ranch Hand
Posts: 54
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
in my latest assignment, below i have been asked to include javadoc commentry as i go along. As im not familiar with this as yet i had a go but i dont think it is of v.high standard. any ideas on how to improve are much appreciated.

My coding:


/**
*This class represents a series of named items held in a
* {@link MostRecent "most recent" list}.
*All items must have a name, this is a String, however if two items
*have the same name they are considered equal
*
*/

public class MostRecent
{

// --------------- FIELDS --------------

/** Constant value of 10 for maximum number of items stored in list*/
private static final int MAX_ITEMS = 10;

/** Integer for items in list*/
private int i;

// ------------- CONSTRUCTOR -------------

/** The constructor is an instance method with the same name as the class
*Procedure used to create and inialise MostRecent list
*/
public MostRecent(){
}

// -------------- METHODS ----------------

/**Update the list
*This method updates the list with the most recently accessed item.
*First it will check to see how many items are already in the list
*Next it will move to the top of the list and then get the name of the item
*Finally it enters the name at the top of the list
*/

/* Update List*/

NamedItem recent = new NamedItem

public void update(NamedItem n){

int [] entry = new int[10];
entry[0] = n.getName();
}

/** Display the list
*This method is to print out the name of the most recently accessed item
*It works on the basis that when i = 0 and i is also less than the maximum
*number of items this will add another item onto the list.
*This latest addition to the list is then presented as standard output.


/* Display List*/

public void display()

{System.out.println("---------------------------");
for (i = 0;
i < MAX_ITEMS;
i++);
{
// print name of ith item to standard output
}
}
;

}

 
Ranch Hand
Posts: 3640
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
Check this.
 
Ranch Hand
Posts: 59
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
Hi there Chris. I have made a few comments on some of your javadoc comments. I hope that some of them are useful.This doesn't quite match the description of your program (in another thread & forum) so I wonder if it is quite accurate. In particular, does the list hold "named items", or just "names"? ie is there anything else to the items other than their names?The comments will be read separately from the code, so they are there to describe the class, not the code. Anyone reading the code knows that MAX_ITEMS is a constant value. Anyone reading the javadoc output doesn't need to know how the limit is implemented. So perhaps "List is limited to 10 items" instead.This is an internal working variable which the javadoc reader should not be told about. And it should not need an internal comment either. Any programmer will assume that a variable called i is a temporary counter, which has no specific meaning outside of any particular loop in which it is used. If it IS important to know that i refers to items in the list, then call it that: itemsInList rather than i.Once again, this doesn't belong in the javadoc output, because it provides no information about this specific class. And it doesn't belong in the internal comments either, because you can assume that all readers will know what a constructor is.It is very important to distinguish between what the code does (interface), and how it does it (implementation). There are a number of important reasons why implementation details should NOT be included in javadoc comments (or any other comments for that matter):
  • Javadoc comments should be about interfaces, what the class does, and how it can and should be used. If other programmers want to know how the class works, they should read the code.
  • The justification for this is the fundamental principle of abstraction. It makes software easier to understand because it exposes important details (interface) and hides other potentially confusing information (implementation) that the reader does not need to know about.
  • Comments that describe what the code does are very rarely useful, and often confusing. There is no way to guarantee that programmers will correctly update the comments when they change the code, so they often become inconsistent with the code, which just causes greater confusion.
  • There is one time when comments about implementation details are useful, and that is when they describe or explain the general design (rather then the line by line details).As for the previous comment. Don't include code explanations in javadoc comments. Furthermore, in this case, they are not an accurate description of either what the code does or how it does it.

    I hope that some of these comments are helpful. Don't worry that I have suggested changes to almost everything that you wrote. Writing good comments is just as difficult as writing good code, but you have to do it without the benefit of the compiler to tell you where you make mistakes. Good luck with the next draft.
     
    Ranch Hand
    Posts: 3061
    • Mark post as helpful
    • send pies
      Number of slices to send:
      Optional 'thank-you' note:
    • Quote
    • Report post to moderator
    You should run the javadoc tool to see if this produces the output you expect. The javadoc tool creates a set of HTML pages with your documentation in it. By default, it looks identical to the Java API docs. The javadoc tool acts a lot like a compiler. That is, it will tell you if there are any errors in your documentation.

    I think your docs won't appear as you expect. Take this portion for example:

    Notice that there is a variable declaration immediately after the comment that is supposed to describe the update() method. If you run the javadoc tool, you will see that this explanation will appear for the variable named recent (if you enable documentation for the correct access level), not for the update() method. This means that you need to move the documentation just before the update() method for it to appear in the correct place in the generated HTML pages.

    Since javadoc produces HTML pages, you can use any HTML tags to format your output. In the majority of documentation this isn't necessary. However, it can be helpful if you want to create links, use an image, or add a list to the documentation. Also, javadoc provides tags that have special meanings. These typically begin with @. In fact, you used the @link tag in one of your javadoc comments. You should also become familiar with the @param and @return tags. These are standard to use with any methods that take parameters and/or return a value. They can provide explanations about the expected values of the parameters and what the return result means.

    For more information about javadoc conventions, you should look here.

    Layne
     
    (instanceof Sidekick)
    Posts: 8791
    • Mark post as helpful
    • send pies
      Number of slices to send:
      Optional 'thank-you' note:
    • Quote
    • Report post to moderator
    The AmbySoft standards have good ideas about JavaDoc, too.

    I lifted a line from the eXtremo guys: If a method requires JavaDoc it's probably sick. I turned that around to a goal of making methods that make doc unnecessary. Clear names and good separation of responsibilities between classes make that pretty easy. That won't really help you get a grade that is based on having JavaDoc but it's worth trying for.

    However I like to document liberally at the package level, only slightly less at the class level. The first line of every class doc winds up on the package summary. Make it count! You can also write "package.html" in each package. This is a good place to explain what this set of classes is for and how and why you might use them.

    I also document things like why I didn't use the more obvious algorithm here, or what external factors made this method change from release 2 to release 3. And sometimes I beg forgiveness for things that I know are bad but I haven't gotten back to fix yet

    Some place I read advice to not start with "This class..." or "This method...". It really clogs up the package summary of classes and the class summary of methods. The same source advised against "represents" at the class level. Just tell what it is or does. Sample through the Sun doc at random to see what the first sentence tells you. Some are better than others, of course.
     
    That which doesn't kill us makes us stronger. I think a piece of pie wouldn't kill me. Tiny ad:
    a bit of art, as a gift, that will fit in a stocking
    https://gardener-gift.com
    reply
      Bookmark Topic Watch Topic
    • New Topic