Issues with JavaDoc [closed]

It's difficult to tell what is being asked here. This question is ambiguous, vague, incomplete, overly broad, or rhetorical and cannot be reasonably answered in its current form. For help clarifying this question so that it can be reopened, visit the help center. Closed 10 years ago.

So I am trying to correctly and fully javadoc comment this block of code but I dont know what all to do and what not to do. Tha开发者_开发技巧nks !

public double largerRoot (double a, double b, double c) throws Exception
{
    double discriminant;
    double root1;
    double root2;

    discriminant = Math.sqrt ( b * b - 4 * a * c );

    if ((discriminant < 0) || (a == 0))
    {
        throw (new Exception("Math Error"));
    }

    root1 = (-b + discriminant) / (2 * a);
    root2 = (-b - discriminant) / (2 * a);

    return Math.max(root1, root2);
    }

---

in eclipse, press Alt + Shift + J

else: google (like this)

---

First: I would rename a b and c parameters with a name that speak.

Second: method/class description : always write javadoc with "Why" in mind. I mean most of the dev write javadoc that explain what the code do... this is kind of helpless since most of the programmer know how to read the code. I always try to describe the class or method as why i did it and what purpose (contract) it should do.

Third: details about parameters is a must (null accepted or not, is there any range..etc)

Fourth: details about the return value.

fifth: reference : @see can be usefull to the javadoc user who want to know about a class you use inside your method.

Hope it help.