This week's book giveaway is in the Open Source forum.
We're giving away four copies of Programmers Guide to Apache Thrift and have Randy Abernethy on-line!
See this thread for details.
Win a copy of Programmers Guide to Apache Thrift this week in the Open Source forum!
  • 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 all forums
this forum made possible by our volunteer staff, including ...
Marshals:
  • Campbell Ritchie
  • Devaka Cooray
  • Knute Snortum
  • Paul Clapham
  • Tim Cooke
Sheriffs:
  • Liutauras Vilda
  • Jeanne Boyarsky
  • Bear Bibeault
Saloon Keepers:
  • Tim Moores
  • Stephan van Hulst
  • Ron McLeod
  • Piet Souris
  • Frits Walraven
Bartenders:
  • Ganesh Patekar
  • Tim Holloway
  • salvin francis

Can you help me improve my javadoc and documentation please  RSS feed

 
Ranch Hand
Posts: 117
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
/**
   * actions method calculates the minimum actions neede to reach from x to y (x<y) with
   * only using the operators +1,*2.
   * @param x -an integer from the user.
   * @param y - an integer form the user.
   * return - an integer number which represents the minimum number to reach from x to y.
   */
   public static int actions(int x,int y)
   {
       // checks if x reached to y or if the given values are vaild
       if(x==y)
           return 0;
           // checks if y is an odd number
       else if (y%2==1)
       return 1+actions(x,y-1);//calls actions method with x and even y,adds 1 to the total counting
       //checks if y/2 is still bigger than or equals to x
       if(x<=y/2)
       return 1+actions(x,y/2);// calls actions method with x and y/2, adds 1 to the total counting
       else
       return 1+actions(x,y-1);// calls actionsmethod with x and y-1, adds 1 to the total counting
   }
 
Ranch Hand
Posts: 37
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
 
Marshal
Posts: 64473
225
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Mae sure your method actually does what it says it does.
  • 1: Be very precise. The documentation comments will form a contract between the programmer and the users, so precision is necessary. +1 and *2 are not operators but arithmetical operations. You didn't say whether () are permissible in the formula.
  • 2: Find some resources about documentation comments, e.g. this Oracle page and then later the appropriate part of Effective Java by Joshua Bloch.
  • 3: Write the first sentence as a very brief description of the class/method/field/constructor you are describing. maybe, “Calculates the fewest steps needed to change x to y using two arithmetical operations.” It ends at the first full stop. Note short note format. This appears in the “details” section and the summary.
  • 4: Write the remainder of the free‑form description, which appears in the “details” section. You are allowed HTML tags, tables, etc. Write as much or as little as you need.
  • 5: After the first @ character, you move into tag mode. Use the tags to document parameters, return values, any exceptions known about, etc.
  • I would say that “actions” isn't a good method name for what you are doing. I am not sure it is a good method name for anything, in fact.
    Be careful what you write.

    Uses Bedžrýczowsky's algorithm.

    Uses Bedžrýczowsky's algorithm. See Bedžrýczowsky, A, Acta Pol Math 28: 121-137 (1931)

    Uses Bedžrýczowsky's algorithm. See Bedžrýczowsky, A, Acta Pol Math 28: 121-137 (1931). English translation at some link or other.

    The current implementation uses Bedžrýczowsky's algorithm. See Bedžrýczowsky, A, Acta Pol Math 28: 121-137 (1931). English translation at some link or other.

    The current implementation uses Bedžrýczowsky's algorithm, but this may change in future implementations. See Bedžrýczowsky, A, Acta Pol Math 28: 121-137 (1931). English translation at some link or other.

    Each of those comments goes a bit further than its predecessor, but the first three commit you to using Bedžrýczowsky's algorithm for ever. The English translation is useful for people who don't realise that Warsaw was one the world's mathematical centres in the 1930s, and it will tell you whether there really is such a thing as Bedžrýczowsky's algorithm
    Your @param tags should say somewhere that y must be strictly greater than x. If you throw an illegal argument exception, that needs a @throws tags, too.

    Please use the code button to preserve indentation and syntax highlighting.
     
    • Post Reply Bookmark Topic Watch Topic
    • New Topic
    Boost this thread!