Bug 30562 - [tasklist/javadoc] Reports missing Javadoc for override method
[tasklist/javadoc] Reports missing Javadoc for override method
Status: RESOLVED FIXED
Product: contrib
Classification: Unclassified
Component: Tasklist
3.x
PC Linux
: P4 (vote)
: 3.x
Assigned To: Torbjorn Norbye
tasklist-issues@contrib
:
Depends on:
Blocks:
  Show dependency treegraph
 
Reported: 2003-01-31 23:24 UTC by Jesse Glick
Modified: 2003-12-11 14:46 UTC (History)
0 users

See Also:
Issue Type: DEFECT
:


Attachments

Note You need to log in before you can comment on or make changes to this bug.
Description Jesse Glick 2003-01-31 23:24:11 UTC
tasklist.javadoc/1 [0.8.25 200301310100]

If you are overriding a method from a superclass
(or implementing a method from an interface or
abstract class), you do not necessarily need a
Javadoc comment for it. Often the declaring class
will supply Javadoc describing what the contract
of the method is, and assuming you are following
that contract, there is nothing more to say. (Your
class Javadoc and constructors or factory methods
may describe everything you want to specify.)

For this reason, the Javadoc tool as of JDK 1.3
automatically fills in Javadoc from the declaring
class for you if it needs to.

Therefore I think the tasklist/javadoc suggestions
should omit override methods, since they are often
just noise and not real problems. In fact it is
policy for Open APIs source code *not* to add
Javadoc to overrides without adding more
information, as there was a documentation
maintenance problem otherwise.

(Ideally override methods should be omitted only
if the declaring class had a Javadoc comment for
that method, but in practice many declaring
classes will be available only in bytecode form,
so this refinement cannot work.)
Comment 1 Torbjorn Norbye 2003-02-01 00:12:38 UTC
Agreed.

I'm currently using the AutoCommenter code for the Auto Comment tool -
it has the same limitation, right? (Or perhaps I'm not using it right).  

Is there an easy way to tell if a MemberElement is overriding
something in super? Do I have to iterate up the Class hierarchy and do
method lookups in each? Is there any code you know if in NetBeans
which does the right thing here (for example, does the popup
completion javadoc window look up the parent javadoc?) that I can
leverage/copy?
Comment 2 Torbjorn Norbye 2003-02-01 01:37:42 UTC
Duh, I guess checking with the immediate superclass should be enough.
Comment 3 Jesse Glick 2003-02-01 02:24:12 UTC
Immediate superclass (don't forget interfaces!) may not suffice:

public interface A {
    /** some doc */
    void x();
    /** more doc */
    void y();
}
public abstract class B implements A {
    // inherits doc from A
    public final void x() {}
}
public class C extends B {
    // inherits doc from A
    public final void y() {}
}

Sorry, forgot to give references. Issue #25429 for popup Javadoc;
issue #24406 for Auto Comment; issue #7115 for interface
synchronization. You can tell I have a pet peeve here! :-)
Comment 4 Torbjorn Norbye 2003-02-01 23:05:17 UTC
Fixed. It only deals with methods. A class missing a javadoc will be
listed as needing a javadoc even if its parent class has a javadoc;
this seems right to me (if a class has the same description as its
parent, why is it a different class? Something must differentiate it,
and that ought to be documented in the class javadoc.)

Fix available in tasklist.javadoc/1 0.8.26.
Comment 5 Jesse Glick 2003-02-03 14:49:16 UTC
Right, of course classes and constructors and fields and static
methods cannot inherit Javadoc comments - only instance methods whose
signature matches that of the super signature (possibly with protected
-> public).
Comment 6 Jesse Glick 2003-07-16 00:33:54 UTC
org.netbeans.modules.tasklist.javadoc/1 [1.1 200304230100]

Does not appear to be fixed to me.

0. Suggestions view open.

1. Create package test in sampledir.

2. Create interface Foo in it:

package test;
/** X */
public interface Foo {
    /** does x */
    void x();
}

(Save it.) No Javadoc warnings here. (Ignore any copyright warning.)

3. Create empty class FooImpl, make it impl Foo:

package test;
/** Y */
public class FooImpl implements Foo {
    public void x() {}
}

(Save it.) Suggestions window incorrectly says:

"x: Javadoc comment is missing."
Comment 7 Jesse Glick 2003-07-16 01:21:49 UTC
Code was only looking for class name, not FQN, when using
ClassElement.forName.

Also I noticed that adding "extends Object" affected whether a docless
toString() would be reported. Fixed - everything now assumed to
implicitly extend Object.

Checking in tasklist/javadoc/manifest.mf;
/cvs/tasklist/javadoc/manifest.mf,v  <--  manifest.mf
new revision: 1.18; previous revision: 1.17
done
Checking in tasklist/javadoc/module-updates.txt;
/cvs/tasklist/javadoc/module-updates.txt,v  <--  module-updates.txt
new revision: 1.6; previous revision: 1.5
done
Checking in
tasklist/javadoc/src/org/netbeans/modules/tasklist/javadoc/DocSuggester.java;
/cvs/tasklist/javadoc/src/org/netbeans/modules/tasklist/javadoc/DocSuggester.java,v
 <--  DocSuggester.java
new revision: 1.14; previous revision: 1.13
done
Comment 8 Jesse Glick 2003-07-16 01:25:04 UTC
BTW if you extend/implement a class for which you have only bytecode,
and no mounted source, it will complain although the original method
may have in fact had Javadoc. You thus need to mount sources, incl.
e.g. the JRE.
Comment 9 Torbjorn Norbye 2003-07-16 06:46:48 UTC
I've merged your fix to the dev35 branch, the tasklist-3.5 compatible
branch which is feature compatible with the tasklist 4.0 version (trunk).


By use of this website, you agree to the NetBeans Policies and Terms of Use. © 2012, Oracle Corporation and/or its affiliates. Sponsored by Oracle logo