It would be nice to have a high-level design outline concerning interfaces and *objects* returned from methods of the com.sun.source.doctree package.

One consideration of such an outline would be certain methods returning surprisingly broad types. For example, getDescription() might be naively expected to return TextTree. It should be explained that the reason that method returns List<? extends DocTree> instead is recursive composition. For example, getDescription() might return ErroneousTree, StartElementTree, EndElementTree or AttributeTree, neither of which is a subtype of TextTree.

Another consideration is the order of elements in lists. The specification should explicitly say how the order of elements in List<? extends DocTree> correspond to that of in source. (DocTree API doesn't provide access to the start position of a node.)