• 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
  • Liutauras Vilda
  • Bear Bibeault
  • Tim Cooke
  • Junilu Lacar
Sheriffs:
  • Paul Clapham
  • Devaka Cooray
  • Knute Snortum
Saloon Keepers:
  • Ron McLeod
  • Tim Moores
  • Stephan van Hulst
  • Tim Holloway
  • Frits Walraven
Bartenders:
  • Carey Brown
  • salvin francis
  • Claude Moore

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

 
Ranch Hand
Posts: 115
  • 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: 35
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
 
Marshal
Posts: 64179
215
  • 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.
     
    Watchya got in that poodle gun? Anything for me? Or this tiny ad?
    Create Edit Print & Convert PDF Using Free API with Java
    https://coderanch.com/wiki/703735/Create-Convert-PDF-Free-Spire
    • Post Reply Bookmark Topic Watch Topic
    • New Topic
    Boost this thread!