Support doc-comment tags that can be inline or block tags

Summary

Update the Taglet API to permit tags that may individually be used either as inline tags or block tags.

Problem

Currently, taglets (which provide the implementations for tags) are constrained to support either inline tags or block tags, but not both for the same tag. There are good use-cases for which it would be useful for a tag to be usable as either an inline tag or a block tag. Such use-cases are typically for references to related items, where it may desirable to make the reference inline or in a summary list at the end of the comment. For example,

    /**
    * This tree supports instances of method declarations ({@jls 8.4 Method Declarations}).
    */  

    /**
    * This tree supports instances of method declarations.
    *
    * @jls 8.4 Method Declarations
    */  

The constraint is primarily embodied in the method Taglet.isInline() which determines whether the tag is an inline tag or not. By implication, if it is not an inline tag, it is a block tag.

Solution

Add a new method Taglet.isBlock() which separately and explicitly defines whether the tag is a block tag. The method will have a default implementation of return !isInline(), to reflect the current semantics, but new tags could elect to return true for both the isInline() and isBlock() methods, allowing the tag to be used in either form.

The specification of the existing isInline() method will need to be adjusted to remove the implication that if a tag is not an inline tag then it must be a block tag.

Specification

A specdiff of the changes to the Taglet class is attached. It can also be viewed online.

The primary change is the addition of the new method Taglet.isBlock(), with some related updates to other methods to accommodate the new behavior.

There is an unrelated cosmetic change to Taglet.Location to be more accurate about the specification for Location.TYPE.