Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-8212145

Support inline tags in block tag descriptions

XMLWordPrintable

    • Icon: Enhancement Enhancement
    • Resolution: Cannot Reproduce
    • Icon: P4 P4
    • 21
    • 12
    • tools

      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.

            jjg Jonathan Gibbons
            jjg Jonathan Gibbons
            Votes:
            0 Vote for this issue
            Watchers:
            3 Start watching this issue

              Created:
              Updated:
              Resolved: