Description Martin Aeschlimann 2005-02-08 09:32:08 EST

20050208

This is a issue we already discussed, but after a long discussion with Dani I
decided to bring this up again:

The current implementation of 'report non-visible references' is not useful as
it does a 'access visibility validation', a test that is not known to the
Javadoc tool. Instead the Javadoc tool only cares about 'documentation
visibility': The setting that specifies how visible elements must be to have a
comment generated to the doc. 

package pack1;
/**
 * @see B#fooPriv()
 * @see B#fooPack()
 * @see B#fooProt()
 */
public class A {
}

package pack2;
public class B {
   private void fooPriv() {}
   void fooPack() {}
   protected void fooProt() {}
}

When creating Javadoc, you tell the tool which element to document. E.g. you
say, only document elements with visibiliy 'public'. The Javadoc preference page
should also have a field to allow to specify that visibility. All references
that go a field less visible than that should get a warning as they are
references to comments that are not going to be in the documentation.

The current 'visibility' check does something else: All 3 see tags are marked as
'non-visible'. The implementation checks if class A could see (= call) fooProt
of B. Of course it can't, B is not in a hierarchy of A. But for documentation
reasons that does not matter. Maybe the comment of fooProt() has an important
note about A.