Name: skT45625 Date: 04/27/2000
java version "1.2.2"
Classic VM (build JDK-1.2.2-001, green threads, sunwjit)


There are several closed bug reports on this issue but I think I have a new
slant on it.

We use javadoc to generate both an API from our code, and (using -private) we
document our software design. We are curently reviewing our design prior to
beginning the detail coding. Yes we have already coded all the classes and
interfaces and method signatures, but all our methods currently have no
effective body.

We are finding it difficult during the review process to review the concurrency
aspects of the design because "synchronized" is omitted from the java docs. The
same is true for "native",

All the comments passing this issue off as not a bug (see 4214145 and others,
also see http://java.sun.com/products/jdk/javadoc/details-of-apispecs.html),
seem to be based on the fact that how you do concurrency is not an API issue. I
agree with that, BUT javadocs can be used for more than just generating API's.

There seems to be an inconsistency in javadocs which has the -private tag to
generate non api information, but doesn't, and cannot show synchronized and
native.

  To achieve consistency javadoc should either have an option to document
synchronized and native modifiers, or the -private option should be dropped (and
I am NOT advocating the latter).

IF you are with me so far, then we need to look how this can be done...

Technically the output is not difficult since the doclet api provides the
modifiers of a method. (see ProgramelementDoc.modifiers() )

There are two ways javadoc could be controlled to generate this-

1) When -private is specified then synchronized and native are shown, and when
-private is not specified they are omitted.

or

2) separate -synchronized and -native options to control the output of these.

With either of these solutions, API's can be generated which omit the native and
synchronized modifiers as has rightly been argued that they should, AND we CAN
include them in our documents for design review which I believe we should
rightly be able to, but currently can't.
(Review ID: 103687)
======================================================================