JDK-8310452 : Allow javadoc to process unnamed classes
  • Type: CSR
  • Component: tools
  • Sub-Component: javadoc(tool)
  • Priority: P3
  • Status: Closed
  • Resolution: Approved
  • Fix Versions: 21,22
  • Submitted: 2023-06-20
  • Updated: 2023-12-01
  • Resolved: 2023-07-12
Related Reports
CSR :  
Relates :  
Relates :  
Relates :  
Relates :  
Description
Summary
-------

`javadoc` is unable to process files containing unnamed classes.

Problem
-------

`javadoc` is unable to process files containing unnamed classes because they are marked synthetic.

Solution
--------

Specifically allow classes that are synthetic and are unnamed to generate javadoc.

Specification
-------------

Remove the statement "The javadoc tool will fail when asked to generate API documentation for a Java file with an unnamed class, as unnamed classes do not define any API accessible from other classes. This behavior may change in a future release." from https://bugs.openjdk.org/browse/JDK-8302326 JEP 445: Unnamed Classes and Instance Main Methods (Preview).

Change the first paragraph of the Description section of the `javadoc` tool man page to include unnamed classes.

```
diff --git a/closed/src/jdk.javadoc/share/man/javadoc.md b/closed/src/jdk.javadoc/share/man/javadoc.md
index 14b90e1c16..105db4c245 100644
--- a/closed/src/jdk.javadoc/share/man/javadoc.md
+++ b/closed/src/jdk.javadoc/share/man/javadoc.md
@@ -46,10 +46,10 @@ javadoc - generate HTML pages of API documentation from Java source files
 
 The `javadoc` tool parses the declarations and documentation comments in a set
 of Java source files and produces corresponding HTML pages that describe (by
-default) the public and protected classes, nested classes (but not anonymous
-inner classes), interfaces, constructors, methods, and fields. You can use the
-`javadoc` tool to generate the API documentation or the implementation
-documentation for a set of source files.
+default) the public and protected classes, nested and unnamed classes (but not
+anonymous inner classes), interfaces, constructors, methods, and fields.
+You can use the`javadoc` tool to generate the API documentation or the
+implementation documentation for a set of source files.
 
 You can run the `javadoc` tool on entire packages, individual source files, or
 both. When documenting entire packages, you can use the `-subpackages` option
```







Comments
In any case, this CSR has been outdated. If nothing else, JEP 463 renamed the feature: those classes are now called "implicit", not "unnamed".
29-11-2023

While the related JDK-8309595 was resolved a few months ago, I cannot seem to find a commit that brings this CSR change to the javadoc man page.
29-11-2023

Moving to Approved.
12-07-2023

Updated. "unnamed classes" needs to be present to meet the requirement of recorded spec change for this CSR.
12-07-2023

I would recommend reordering the list or otherwise editing the list. Right now, "members of unnamed classes" comes between "classes" and "interfaces", before "constructors", "methods", "fields". Indeed, since the "members of unnamed classes" *are* "methods" and "fields", I wonder if "members of unnamed classes" needs to be called out at all. If you want a specific suggestion, I would insert just ", unnamed classes" after the phrase about nested classes. (i.e. omit the "members of" words). Or just delete "unnamed classes". Or change to "nested and unnamed classes (but not anonymous inner classes)"
12-07-2023

Moving to Provisional, not Approved. [~jlaskey], please formulate a spec change for this behavior that could be documented somewhat, i.e. some specification related to javadoc. [~jjg] or [~hannesw], please review this CSR.
26-06-2023