Dangling class-level javadoc comments in JDK

[Pavel Rappo]

> 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