#387 Java 1.5 paramerized types broken

release_4.0
closed
None
5
2012-10-10
2005-11-29
Jon Schewe
No

If I have a class declaration like so:
/
* Creates queueObjects as needed.

/
abstract /package/ class
QueueObjectFactory<QueueObject_TYPE extends="" QueueObject=""> {
...
}

and run checkstyle 4.0 on it, I get the following warning:
/net/users/jschewe/projects/argus/working-dir/java/src/scyllarus/dbutils/QueueObjectFactory.java:28:
Type Javadoc comment is missing an @param
<QueueObject_TYPE> tag.

If I change it to this:
/
* Creates queueObjects as needed.

* @param QueueObject_TYPE the type of queue object
that this factory will create
/
abstract /package/ class
QueueObjectFactory<QueueObject_TYPE extends="" QueueObject=""> {
...
}
I get the following warning:
/net/users/jschewe/projects/argus/working-dir/java/src/scyllarus/dbutils/QueueObjectFactory.java:27:4:
Unused Javadoc tag.

Seems to me that there's no right answer here,
according to checkstyle.

Discussion

  • Logged In: YES
    user_id=1022106

    Try:

    @param <QueueObject_TYPE>

     
  • Jon Schewe
    Jon Schewe
    2005-11-29

    Logged In: YES
    user_id=209980

    Nope, that doesn't work either.

    Running Checkstyle 4.0 on 58 files
    /net/users/jschewe/projects/argus/working-dir/java/src/scyllarus/dbutils/SmartQueue.java:31:
    Type Javadoc comment is missing an @param <QueueObject_TYPE>
    tag.

     
  • Oliver Burn
    Oliver Burn
    2005-11-29

    Logged In: YES
    user_id=218824

    What if you change:

    abstract /package/ class

    to:

    abstract class

     
  • Jon Schewe
    Jon Schewe
    2005-11-29

    Logged In: YES
    user_id=209980

    That doesn't hlep either.

     
  • Logged In: YES
    user_id=1022106

    What about:

    @param <QueueObject_TYPE extends="" QueueObject="">

    I'm not sure this is even correct and I'd try it myself but
    I don't have access to an environment right now.

     
  • Jon Schewe
    Jon Schewe
    2005-11-29

    Logged In: YES
    user_id=209980

    That doesn't work either. What does Sun state is the
    correct way to document this? I've not seen any
    documentation from Sun on this yet.

     
  • Jon Schewe
    Jon Schewe
    2005-11-29

    Logged In: YES
    user_id=209980

    Ok, then according to that, this is what should pass:
    /
    * Creates queueObjects as needed.

    * @param <QueueObject_TYPE> the type of queue object that
    this factory will create
    /
    abstract /package/ class
    QueueObjectFactory<QueueObject_TYPE extends="" QueueObject=""> {

    However I get this from checkstyle:
    Running Checkstyle 4.0 on 58 files
    /net/users/jschewe/projects/argus/working-dir/java/src/scyllarus/dbutils/SmartQueue.java:31:
    Type Javadoc comment is missing an @param <QueueObject_TYPE>
    tag.

    It seems that checkstyle just doesn't understand the extends
    syntax. If I do the following, it does work:
    /
    * Add class comment here!

    * @param <T> type

    */
    public class Foo<T> {

     
  • Logged In: YES
    user_id=1022106

    It looks like you're right. We don't seem to handle the
    extends properly. Thanks for your help in identifying what's
    going on. I will work on a fix.

     
  • Logged In: YES
    user_id=1022106

    I'm having real trouble reproducing this (however I can find
    what appears to be a related bug).

    Could you try:
    @param QueueObject the type of queue object that this
    factory will create

    This will help confirm my suspicions (that it's the
    underscore that's the problem)

     
  • Logged In: YES
    user_id=1022106

    I created the a file as below and the output is correct
    using sun_checks.xml. Removing the @param causes Checkstyle
    to complain, replacing it causes Checkstyle to be silent on
    the matter as it should be. Can you provide a standalone
    java file that you can submit to us that reproduces this
    problem?

    The bug I mentioned in my last response is actually in
    unconnected code (JavadocStyleCheck) so my suggestion
    probably won't work for you.

    /
    Blah blah.

    */
    public class QueueObjectFactory
    {
    }

    /
    Blah blah.

    */
    public class QueueObject
    {
    }

    /
    Creates queueObjects as needed.
    @param <QueueObject_TYPE> the type of queue object
    that this factory will create
    /
    abstract /
    package*/ class
    QueueObjectFactory<QueueObject_TYPE extends="" QueueObject=""> {

    }

     
  • Jon Schewe
    Jon Schewe
    2005-12-01

    Logged In: YES
    user_id=209980

    So it's working. Turns out that there's another file in the
    same codebase that it was complaining about. Notice that my
    error messages were about SmartQueue.java, but my examples
    were all QueueObjectFactory? Sorry guys for the run around.
    At least I now know the right way to document these.
    Thanks for that.

    The following works:
    /
    * Creates queueObjects as needed.

    * @param <QueueObject_TYPE> the type of queue object that
    this factory will create
    /
    abstract /package/ class
    QueueObjectFactory<QueueObject_TYPE extends="" QueueObject=""> {
    ...
    }

     
  • Logged In: YES
    user_id=1022106

    Yes, I did notice the naming difference but since the class
    was package visible it could easily have lived in
    SmartQueue.java

    I'm glad it's working for you and it's helped me spot a bug...