This issue has been tracked via SCR-0454: "javadoc should hide documentation which is not part of public API" (see this link), and a DP-CCB action item:
![[Note]](../../admonitions/note.gif) | AI 140605/1 |
|---|---|
RH, as part of the DP documentation group, to make a counter proposal how documentation for private classes, methods, etc, can be hidden in javadoc |
The question is how to exclude certain information from the javadoc at package level, but also classes, methods and even fields.
Excluding packages: This is possible using the javadocexclude directive in the jake.config files. You can specify any (sub-) package that should be excluded from the javadoc generation process.
Excluding classes: The exclusion of classes should normally be done by assigning proper modifiers to your classes. You can make your classes package friendly (meaning the class can be accessed only from within the package) by *not* specifying any modifier. Unfortunately, the guidelines for package structure in the HCSS contradict this rule since public APIs should be placed inside a sub-package called 'api', while implementations should be put into the sub-package 'impl'. In order to make this work, classes in both packages should have public access state. A sub-package 'impl' could however be excluded using the javadocexclude as described above.
Excluding methods and fields: For methods and fields the same guideline applies to use the normal Java access modifiers to define the access level of your methods. This is however very restricting since we don't want to see e.g. all jython hooks that are build into our code. Part of this can be solved by extracting interfaces for these methods, but there are surely occasions where we can not do this in a reasonable way. There is a need to exclude methods from the documentation even if they have public access state.
The first recommendation is that developers should re-visit their packages and classes and check if sub-packages and classes can be made non-public in order to remove them from the javadoc. Second we need a mechanism to make methods and field disappear from the javadoc. Several options were investigated:
Write our own Doclet/Taglet/Filter classes to exclude parts of the javadoc. This is a work package that needs considerable effort, while (see option 3) it has been done for us by others.
Use the Java 1.5 annotation mechanism We still need to write our own classes to cope with these annotations.
Use a third party library, like yDoc. yDoc was purchased and (again) investigated for this purpose. The (single user) license costs 138 EURO. This product implements some useful Doclets/Taglets and Filters for javadoc. One of the filters implements exactly the request made by this SCR, i.e. if you put the tag @y.exclude anywhere in your javadoc (for class, method or fields) that piece of javadoc will not be used during generation. yDoc therefore fulfills the requirement. It is however not needed for all developers to have a yDoc license since the standard javadoc tool will simple raise a warning and ignore the unknown tag. In addition, yDoc provides for each class in the javadoc a class diagram with dependencies and associations, showing inheritance etc... One thing I did not investigate (amongst many others :-) is the performance of this tool against normal javadoc.