@Overrides and Javadoc

[Rhino]

I'm still a little fuzzy on the best way to document it when I override an
inherited method.

At the moment, I have a JApplet that overrides the JApplet init() method and
have an @Override that is not within a Javadoc comment, like this:

/**
* This is my init method.
*/
@Override
public void init() {

// my code

}

The compiler has no trouble with this but Javadoc, invoked via Ant,
complains:

[javadoc] Loading source file E:\FooApplet.java...

[javadoc] E:\FooApplet.java:75: illegal character: \64

[javadoc] @Override

[javadoc] ^

If I omit the @Override tag that is outside of the Javadoc comment and use
an @Override tag that is within the Javadoc comment, my Javadoc error goes
away but I get a warning from the compiler that I should be using a
non-Javadoc @Override on my init() method.

If I have both @Override tags, one within the Javadoc comment and one
outside, Javadoc still complains about the one that is not within the
Javadoc comment.

I know that I can set the compiler to 'ignore' the overriding of methods
like init() but I don't want to do that in this case. How can I be sure not
to get a compiler warning but also get Javadoc to accept my @Override tags?
I'd be willing to tell Javadoc to ignore such things if there is a switch
for that but I haven't found one yet.

Can anyone enlighten me on the right way to handle this situation?

 

[Roedy Green]

The compiler has no trouble with this but Javadoc, invoked via Ant,
complains:

this is a new feature. Is ant getting hold of an old JavaDoc?

 

[Rhino]

this is a new feature. Is ant getting hold of an old JavaDoc?

No, I'm pretty sure that's not the case.

I'm generating the Javadocs via the javadoc task in Ant 1.6.5; I've got
JAVA_HOME set to d:\Java\jdk1.5.0_06 and I've got the following parameters
in my javadoc task:

executable="d:\Java\jdk1.5.0_06\bin\javadoc" source="1.5".

There is a javadoc.exe in d:\Java\jdk1.5.0_06\bin; it is timestamped
10/11/2005 12:37 PM and is 49,275 bytes in size. I assume that is a current
javadoc.

Rhino

 

[Rhino]

No, I'm pretty sure that's not the case.

I'm generating the Javadocs via the javadoc task in Ant 1.6.5; I've got
JAVA_HOME set to d:\Java\jdk1.5.0_06 and I've got the following parameters
in my javadoc task:

executable="d:\Java\jdk1.5.0_06\bin\javadoc" source="1.5".

There is a javadoc.exe in d:\Java\jdk1.5.0_06\bin; it is timestamped
10/11/2005 12:37 PM and is 49,275 bytes in size. I assume that is a
current javadoc.

Sorry! I should have added something very important: when I added the
'executable' and 'source' parameters to the javadoc task, which I'd thought
of and tried independently after I posted, the error changed to a warning:

[javadoc] E:\FooApplet.java:79: warning - @Override is an unknown tag.

Obviously, that's an improvement but how do I get rid of the warning too?

Rhino

 

[Chris Smith]

Sorry! I should have added something very important: when I added the
'executable' and 'source' parameters to the javadoc task, which I'd thought
of and tried independently after I posted, the error changed to a warning:

[javadoc] E:\FooApplet.java:79: warning - @Override is an unknown tag.

Obviously, that's an improvement but how do I get rid of the warning too?

First of all, you should NOT put @Override in a JavaDoc comment. Sounds
like that's what you're doing. @Override is an annotation, not a
JavaDoc tag. So move it back out of the JavaDoc comment, and then deal
with whatever problems that causes.

I don't know who initially told you to put @Override in the comment.
Whoever it was, kick them in the shins. They've confused you.

--
www.designacourse.com
The Easiest Way To Train Anyone... Anywhere.

Chris Smith - Lead Software Developer/Technical Trainer
MindIQ Corporation

 

[Rhino]

Sorry! I should have added something very important: when I added the
'executable' and 'source' parameters to the javadoc task, which I'd
thought
of and tried independently after I posted, the error changed to a
warning:

[javadoc] E:\FooApplet.java:79: warning - @Override is an unknown tag.

Obviously, that's an improvement but how do I get rid of the warning too?

First of all, you should NOT put @Override in a JavaDoc comment. Sounds
like that's what you're doing. @Override is an annotation, not a
JavaDoc tag. So move it back out of the JavaDoc comment, and then deal
with whatever problems that causes.

I don't know who initially told you to put @Override in the comment.
Whoever it was, kick them in the shins. They've confused you.

I read it in one of the documents that comes with the API or that is linked
from there; I don't recall which one offhand. I could have sworn that they
@Override in either place would work but that the one outside of the comment
was better but maybe I just misread that. In any case, removing the
@Override from the Javadoc comment got rid of the Javadoc warning, as I
wanted, and the surviving @Override annotation is preventing the compiler
warning so I've gotten exactly what I wanted.

Thank you!

Rhino

 

[Chris Smith]

I read it in one of the documents that comes with the API or that is linked
from there; I don't recall which one offhand. I could have sworn that they
@Override in either place would work but that the one outside of the comment
was better but maybe I just misread that.

Hmm. Maybe you were reading about @Deprecated instead. In that case,
there IS an @deprecated JavaDoc tag, and you should use both that and
the annotation. There is no JavaDoc tag for overriding, though.

--
www.designacourse.com
The Easiest Way To Train Anyone... Anywhere.

Chris Smith - Lead Software Developer/Technical Trainer
MindIQ Corporation