The Taglet API provides an Element to 'toString', which conveys where in the source code the taglet is being applied. This *usually* corresponds to the location in the documentation tree where the taglet is being applied (although this mapping is nontrivial); but sometimes the comment on an Element can be lifted into another context (the package or module page, a summary page like 'new-list.html', etc), and then the Element is of no help.

Taglets that generate relative URLs need to know where they are located in the documentation tree so that they can navigate to the targeted resource. The JSpec (@jls, @jvms) and ToolGuide (@toolGuide) Taglets in the JDK are examples of this: they can produce paths from the documentation root to other resources, but need to know how to get to the documentation root. When they derive a URL based on the Element, some generated URLs are broken links.

To address this, the Taglet interface could be enhanced with a default 'toString' overload that takes a third parameter that captures either the current file or a path to the documentation root—a String, a Path, or something similar. (The current file may be more useful for resources located in subtrees of the documentation tree.) Implementations that choose to override the new 'toString' would also need to override the old 'toString', perhaps by throwing an exception.

Another approach would be to override 'toString' with a third "context" parameter, an object that provides URL-mapping functionality today, and maybe other behaviors in the future.

JDK-8373909 applies a hack to make the JDK taglets work, but this bug should undo that hack and use the new API instead.