Javadocs empty details for parameters starting with "@"

[theodorekwok]

Hi Prof, suppose the JavaDoc contains "@param" or "@return" or "@throws" but the author did not write any details for them, is it considered a coding standard violation?

for example something like this below where the method has params, return and throws /* Returns lateral location of the specified position. * If the position is unset, NaN is returned. * * @param * @param * @param * @return * @throws */ `

[okkhoy]

Yes. You need to mention what each is for.

[theodorekwok]

Thanks prof!

[richwill28]

@okkhoy

On a related note, is omitting @param considered a violation? (even if it may be obvious) For example..

/**
 * Move the center of the object to the given point.
 */
void moveTo(Point c) {
    this.c = c;
}

[okkhoy]

Using @param is not mandatory if it is obvious; however, if you use it, it should not be empty.

[naijie2108]

@okkhoy

Adding on the question by @richwill28, is omitting "@return" and "@throws" if they are obvious considered violations?

[okkhoy]

TL;DR: The same argument applies to those as well.

Details: However, in reality, @throws would be due to some specific reason that may not be obvious. Hence, you may have to include details about the @throws blocks. Again, if it is quite obvious, you can skip it.