-
Enhancement
-
Resolution: Cannot Reproduce
-
P4
-
12
This is an Enhancement which is a generalization of, and fix for, Bug JDK-6344777.
The general issue is that inline tags are not supported in the descriptions of block tags. It would be particularly nice to be able to support {@link} tags in various tags, but it may also be there is a general solution here.
This grep command shows the tags which contain a syntactic component named description or label:
$ grep -E '^\*.*(escription|label)_' closed/src/jdk.javadoc/share/specs/doc-comment-spec.md
* `@exception` _class-name_ _description_
* `@param` _parameter-name_ _description_
* `@param` `<`_type-parameter-name_`>` _description_
* `@provides` _service-type_ _description_
* `@return` _description_
* `@see` `<a href="`_url_`">`_label_`</a>`
* `@see` _package_`.`_class_`#`_member_ _label_
* `@serial` _field-description_
* `@serialData` _data-description_
* `@serialField` _field-name_ _field-type_ _field-description_
* `@throws` _class-name_ _description_
* `@uses` _service-type_ _description_
* `{@index` _word_ _description_ `}`
* `{@index "`_phrase_`"` _description_ `}`
* `{@link` _package_`.`_class_`#`_member_ _label_ `}`
* `{@linkplain` _package_`.`_class_`#`_member_ _label_ `}`
It's probably not necessary (or even desirable) to look at the inline tags (i.e. {@index} and {@link}) but for the others, it would be nice to be able to handle inline tags.
Here's an example of how it is -not- done, in HtmlSerialFieldWriter:
Content serialFieldContent = new RawHtml(ch.getText(description));
"It would be nice" if that "new RawHtml(ch.getText(...))" could be replaced by a call to some library method to translate "description" into Content, interpreting any inline tags that may be found.
The general issue is that inline tags are not supported in the descriptions of block tags. It would be particularly nice to be able to support {@link} tags in various tags, but it may also be there is a general solution here.
This grep command shows the tags which contain a syntactic component named description or label:
$ grep -E '^\*.*(escription|label)_' closed/src/jdk.javadoc/share/specs/doc-comment-spec.md
* `@exception` _class-name_ _description_
* `@param` _parameter-name_ _description_
* `@param` `<`_type-parameter-name_`>` _description_
* `@provides` _service-type_ _description_
* `@return` _description_
* `@see` `<a href="`_url_`">`_label_`</a>`
* `@see` _package_`.`_class_`#`_member_ _label_
* `@serial` _field-description_
* `@serialData` _data-description_
* `@serialField` _field-name_ _field-type_ _field-description_
* `@throws` _class-name_ _description_
* `@uses` _service-type_ _description_
* `{@index` _word_ _description_ `}`
* `{@index "`_phrase_`"` _description_ `}`
* `{@link` _package_`.`_class_`#`_member_ _label_ `}`
* `{@linkplain` _package_`.`_class_`#`_member_ _label_ `}`
It's probably not necessary (or even desirable) to look at the inline tags (i.e. {@index} and {@link}) but for the others, it would be nice to be able to handle inline tags.
Here's an example of how it is -not- done, in HtmlSerialFieldWriter:
Content serialFieldContent = new RawHtml(ch.getText(description));
"It would be nice" if that "new RawHtml(ch.getText(...))" could be replaced by a call to some library method to translate "description" into Content, interpreting any inline tags that may be found.
- relates to
-
JDK-6344777 {@link} tags not expanded in serial doc comments
-
- Open
-
-
JDK-8257925 Enable more support for nested inline tags
-
- Resolved
-