Dangling class-level javadoc comments in JDK

[Pavel Rappo]

Just to clarify that example of mine. I didn't mean the package-info.java file. I meant an ordinary file that comprises an interface, class, enum or record. Perhaps a better example from Andrey's list would be this:

    /**
     * A utility package for the java(1), javaw(1) launchers.
     * The following are helper methods that the native launcher uses
     * to perform checks etc. using JNI, see src/share/bin/java.c
     */
    import java.io.File;

In no context can an import statement be documented.

-Pavel

> On 24 Aug 2021, at 16:07, Pavel Rappo <pavel.rappo at oracle.com> wrote:
> 
>> On 24 Aug 2021, at 15:38, Jonathan Gibbons <jonathan.gibbons at oracle.com> wrote:
>> 
>> IIRC, the one in javadoc CommentUtils has recently been fixed.
>> 
>> It might be worth a javac -Xlint option to detect/report such dangling comments.
> 
> How would you currently implement that? Aren't comments on non-documentable constructs discarded early? At what point during compilation and how would you detect, for example, that this doc comment dangles?
> 
>    /**
>     * IOUtils: A collection of IO-related public static methods.
>     */
> 
>    package sun.security.util;
> 
> -Pavel
> 
>> -- Jon
>> 
>> On 8/23/21 11:50 PM, Andrey Turbanov wrote:
>>> Hello.
>>> I found a few internal classes in the JDK codebase which don't have
>>> proper javadoc, but have dangling javadoc-like comments.
>>> Dangling Javadoc comments are ignored by the javadoc tool and IDE.
>>> Perhaps it was intentional to not add proper javadoc to them?
>>> I believe it's better to convert them to proper javadoc to make
>>> developing JDK a bit more friendly within IDE.
>>> What do you think?
>>> 
>>> List of classes:
>>> 
>>> com.sun.beans.editors.BooleanEditor
>>> com.sun.beans.editors.ByteEditor
>>> com.sun.beans.editors.DoubleEditor
>>> com.sun.beans.editors.FloatEditor
>>> com.sun.beans.editors.IntegerEditor
>>> com.sun.beans.editors.LongEditor
>>> com.sun.beans.editors.NumberEditor
>>> com.sun.beans.editors.ShortEditor
>>> com.sun.jndi.toolkit.dir.ContainmentFilter
>>> com.sun.jndi.toolkit.dir.LazySearchEnumerationImpl
>>> com.sun.security.auth.module.Crypt
>>> java.math.MutableBigInteger
>>> java.net.DefaultInterface
>>> javax.swing.GraphicsWrapper
>>> jdk.internal.access.JavaAWTFontAccess
>>> jdk.javadoc.internal.doclets.toolkit.CommentUtils
>>> sun.awt.X11.XAtom
>>> sun.awt.X11.XAwtState
>>> sun.java2d.xr.XRBackend
>>> sun.java2d.xr.XRDrawLine
>>> sun.jvm.hotspot.debugger.PageCache
>>> sun.jvm.hotspot.runtime.JavaThreadFactory
>>> sun.jvm.hotspot.utilities.Interval
>>> sun.jvm.hotspot.utilities.MessageQueueBackend
>>> sun.jvm.hotspot.utilities.RBTree
>>> sun.launcher.LauncherHelper
>>> sun.net.www.content.text.plain
>>> sun.net.www.protocol.file.FileURLConnection
>>> sun.nio.ch.Interruptible
>>> sun.security.pkcs.ParsingException
>>> sun.security.provider.SeedGenerator
>>> sun.security.util.ByteArrayTagOrder
>>> sun.security.util.IOUtils
>>> 
>>> 
>>> Andrey Turbanov
>