Dangling class-level javadoc comments in JDK

[Jonathan Gibbons]

The poor-man's solution would be to detect common cases, with the 
comment appearing before a package or import statement.

A more advanced solution would have to be in the lexer or parser, 
detecting that there is a "unused" comment when creating a tree node.

-- Jon

On 8/24/21 8:07 AM, Pavel Rappo 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