#395 JavaDoc no longer handles @see correct in 4.0

Future
wont-fix
nobody
5
2014-02-07
2005-12-07
ajbanck
No

In 4.0 b6 and before it was possible the @see tag
allows skipping the need to define all required tags.
This also worked for methods that do not inherited the
tags, so inheritDoc can't be used.

Sample of code that passed 4.0b6 validation but fails
in 4.0 final:

/
Tests the see tag.
@since creation
*/
public class SeeClass {

/**
 * First method.
 *
 * @param aName the name to use in this method
 * @param aObject Object to use in this method
 * @throws Exception if <em>aParameter</em> is invalid
 */
public void doSomething(String aName, Object

aObject) throws Exception {
}

/**
 * Second method.
 * @see #doSomething(String, Object)
 */
public void doSomething(String aName) throws

Exception {
doSomething(aName);
}
}

Discussion

  • Oleg Sukhodolsky

    Logged In: YES
    user_id=746148

    This is because of fix for 1290379 (@see and
    @inheritDoc behavior in JavadocMethod).
    Now if you do not want to write complete javadoc you should
    use {@inheritDoc} instead of @see.
    Unfortunately the documentation wasn't updated (see 1369615
    (JavaDoc test)).

    So, I'm closing this bug. If you disagree - feel free to
    reopen it (with justification :)

     
  • ajbanck

    ajbanck - 2005-12-07

    Logged In: YES
    user_id=1263765

    The second method does not inherit from the first method, so
    it doesn't make sence to use {@inheritDoc} here. I tried it
    out and this tag doesn't work in this situation.

     
  • Oleg Sukhodolsky

    Logged In: YES
    user_id=746148

    If this is not an inherited method, then you shouldn't
    use {@inheritDoc}.
    BTW why do you think that
    /
    Second method.
    @see #doSomething(String, Object)
    */
    is a good example of javadoc?
    it doesn't specify neither param nor exception.
    Of course a human being can understand it, but the check is
    suppose to be more restrictive.
    I suspect that it used to work because of some bug which was
    fixed.

     
  • ajbanck

    ajbanck - 2005-12-15

    Logged In: YES
    user_id=1263765

    I do agree this is not the best way to do Javadoc.
    Problem is that this is a sudden change in the logic applied
    In our code we have 807 methods that use this old Javadoc
    'hole', so currently unable to upgrade from 4.0b6 to final

     
  • Oliver Burn

    Oliver Burn - 2005-12-15

    Logged In: YES
    user_id=218824

    ajbanck, I can fully appreciate where you are coming from, I
    believe I started off the @see "hole" trick. However, I have
    to agree with Oleg that the current behaviour is the correct
    way to go.

    Of course you can consider developing a patch to Checkstyle
    to allow the "@see" hole. Hence I am changing the type of
    this request to an RFE to support such a feature.

     
  • rjoachim

    rjoachim - 2006-02-12

    Logged In: YES
    user_id=1450563

    As this worked with 3.5 and gave been removed for 4.0 you
    should at minimum provide an option to your users to enable
    this agin. I understand your opinon that the current 4.0
    behaviour is the right one but you should provide an option
    to allow your users to use this work around. In my opinon
    this isn't a new feature and even not a bug but a regresion
    issue that should be fixed asap.

     
  • Ivan Sopov

    Ivan Sopov - 2014-02-07
    • status: open --> wont-fix
     
  • Ivan Sopov

    Ivan Sopov - 2014-02-07

    Closing this as it seems that everyone as got used to the new behavior that it assumed to be correct.

     

Log in to post a comment.

Get latest updates about Open Source Projects, Conferences and News.

Sign up for the SourceForge newsletter:





No, thanks