Summary

Permit {@value} in the documentation comment for a module.

Problem

The {@value} inline tag cannot currently be used in the documentation comment for a module, although it is allowed in all other positions for documentation comments.

The specification is inconsistent. The narrative text says that it may be used in any documentation comment,

When used with the argument package.class#field in any documentation comment, the {@value} tag displays the value of the specified constant.

But, the summary at the end of the specification does not list a module declaration among the sites where the tag may be used. This is the extract of the JDK 11 version of the specification:

Module Declaration
{@author}, {@deprecated}, {@provides}, {@see}, {@since}, {@serialField}, {@uses}, {@version}
{@code}, {@docRoot}, {@index}, {@link}, {@linkplain}, {@literal}, {@summary}

Solution

Update the implementation to permit the {@value} tag to be used in the documentation comments for modules, and amend the specification appropriately.

(Note that the overall format of the summary at the end of the specification has already been changed for JDK 12.)

Specification

The diff for the change to the Documentation Comment Specification for the Standard Doclet is attached.

Here is the change inline:

diff -r 9985a046f1b5 closed/src/jdk.javadoc/share/specs/doc-comment-spec.md
--- a/closed/src/jdk.javadoc/share/specs/doc-comment-spec.md    Sat Oct 13 13:44:51 2018 -0700
+++ b/closed/src/jdk.javadoc/share/specs/doc-comment-spec.md    Thu Oct 25 15:02:31 2018 +0530
@@ -679,7 +679,7 @@
 | [`
{@summary}
`](#summary)              | ✓  | ✓ | ✓ | ✓ | ✓     | ✓ | ✓ |
 | [`@throws`](#throws)                  |          |         |         |         | ✓     | ✓ |         |
 | [`@uses`](#uses)                      |          | ✓ |         |         |             |         |         |
-| [`
{@value}
`](#value)                  | ✓  |         | ✓ | ✓ | ✓     | ✓ | ✓ |
+| [`
{@value}
`](#value)                  | ✓  | ✓ | ✓ | ✓ | ✓     | ✓ | ✓ |
 | [`@version`](#version)                | ✓  | ✓ | ✓ | ✓ |             |         |         |

 Notes: