Will Java ever allow comments to nest?

[Pavel Rappo]

> On 1 Jul 2020, at 21:49, Pavel Rappo <pavel.rappo at oracle.com> wrote:
> 
> Hello,
> 
> JLS specifies that comments do not nest [1]. For example, the below source will not compile
> 
>    $ cat CommentsDoNotNest.java 
>    public class CommentsDoNotNest {
>        /* /* */ */
>    }
> 
>    $ javac CommentsDoNotNest.java 
>    CommentsDoNotNest.java:2: error: illegal start of type
>        /* /* */ */
>                 ^
>    1 error
> 
> Some modern languages allow comments to nest. For example, Swift, F#, and Haskell do that. Why doesn't Java do that? Will Java ever do that?
> 
> I can see cases where nesting would be useful:
> 
> 1. Commenting out long blocks of code that possibly contain `/* ... */` comments.
> 2. Having a character sequence resembling a comment terminator `*/`, for example, in a regex or a glob pattern.

Scratch that. Item 2 has nothing to do with nesting; it's just a standalone `*/`

    $ cat CommentsDoNotNest2.java
    public class CommentsDoNotNest {
        /* The result of "/home/".matches(".*/") is true. */
    }

    $ javac CommentsDoNotNest2.java
    CommentsDoNotNest2.java:2: error: unclosed string literal
        /* The result of "/home/".matches(".*/") is true. */
                                              ^
    CommentsDoNotNest2.java:4: error: reached end of file while parsing
    2 errors

A solution to this is to hide `*/` from the compiler. Depending on the context this can be done differently. If this is a regular comment I could choose between these:

    a. // The result of "/home/".matches(".*/") is true.
    b. /* The result of "/home/".matches(".*" + "/") is true. */

If this is a doc comment I could use HTML entities or tags of the Standard doclet:

    c. /** The result of "/home/".matches(".*/") is true. */
    d. /** The result of "/home/".matches(".*/") is true. */
    e. /** The result of "/home/".matches(".{@literal *}/") is true. */

The problem with [c], [d], and [e], however, is that they make a comment less WYSIWYG. The less a doc comment diverts from WYSIWYG the better: if a doc comment uses a lot of markup, I will need a browser to render that (for example, to copy-paste a snippet into my code).

While experimenting with comments I found that IntelliJ IDEA thinks that these are valid comments:

    /* \u002a/ */
    /* *\u002f */

These comments are invalid for the same reason this is not a valid string literal:

    "Hello,\u000Aworld"

JLS specifies that the compiler translates Unicode escapes as the first step of lexical translation, 2 steps before comments are discarded:

    https://docs.oracle.com/javase/specs/jls/se7/html/jls-3.html

I filed a bug against IDEA:

    https://youtrack.jetbrains.com/issue/IDEA-245018

-Pavel

> 3. Having a `/* ... */` comment within a doc comment `/** ... */`. This is typically used in doc comments of language modeling APIs and, admittedly, is a niche case.
> 
> All of the above can be done today, albeit with much friction.
> 
> Thanks,
> -Pavel
> 
> [1] https://docs.oracle.com/javase/specs/jls/se14/html/jls-3.html#jls-3.7
>