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.ra...@oracle.com> wrote:
>
>> On 24 Aug 2021, at 15:38, Jonathan Gibbons <jonathan.gibb...@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
>
