In comparison with the `com.sun.source.tree` API, the `com.sun.source.doctree` API is specified less formally and less uniformly. That leaves room for guess-work.

One example would be inconsistent use of notation for grammar. Consider various ways of marking optionality of tag elements.

1. The optionality is not marked in any way:

/**
 * A tree node for an {@code @value} inline tag.
 *
 * <pre>
 * {&#064;value reference}
 * </pre>
 *
 * @since 1.8
 */
 
`reference` in `{@value}` is optional.

2. The optionality is marked in prose:

/**
 * A tree node for an {@code @index} inline tag.
 *
 * <pre>
 * {&#064;index keyword optional description}
 * </pre>
 *
 * @since 9
 */
 
This should probably be fixed by choosing a notation for _one-of_ choice and consistently using it.

Another example is under-specification.

1.

/**
 * A tree node for an {@code @summary} inline tag.
 *
 * <pre>
 * {&#064;summary text}
 * </pre>
 *
 * @since 10
 */
 
/**
 * A tree node for an {@code @literal} or {@code @code} inline tag.
 *
 * <pre>
 * {&#064;literal text}
 * {&#064;code text}
 * </pre>
 *
 * @since 1.8
 */

Although both doc comments refer to `text`, the JDK source suggests the semantics of `text` in `@summary` and `@code` differ. While summary's `text` allow inline and HTML tags, code's does not.

2.

/**
 * A tree node for a reference to a Java language element.
 *
 * <pre>
 * package.class#field
 * package.class#method(<i>arg-types</i>)
 * </pre>
 *
 * @since 1.8
 */

Eyeballing JDK suggests there's one more _one-of_: when `package.class` is omitted, meaning the same or the inherited context.

There are probably other examples of things we could improve in this area.

One way to fix that would be to update "Documentation Comment Specification for the Standard Doclet" and then refer to corresponding sections of it from the types of the `com.sun.source.doctree` API rather than fixing that in the API documentation.