Draft JEP for upcoming work on snippets

[Jonathan Gibbons]

On 1/26/21 7:47 AM, Roger Riggs wrote:
>
>   * In the @snippet tag, can the "class=" indicate a module name in
>     addition to the class name?
>
A related question is whether and when it makes sense to specify a 
module name.

The current thinking is that external snippets are searched for in 3 
locations: 1) the local `snippet-files` directory, 2) the enclosing 
class hierarchy, 3) a new search path.

Each location has an inherent notion of whether it is "package-oriented" 
or "module-oriented".

So far, all consideration of the local `snippet-files` directory has 
been that it is package-oriented, and so presumably would not be 
searched when looking for a named module.

The enclosing class hierarchy may be package-oriented (for a typical API 
library) or module-oriented (e.g. for JDK). If no module name is 
specified and the hierarchy is module-oriented, that would presumably 
imply the current module (containing the reference.)

For a new search path, search paths are either package-oriented or 
module-oriented, but not both. At a minimum, we should provide a new 
package-oriented search path (e.g. --snippet-path); if there is 
sufficient interest/demand, we could provide a new module-oriented 
search path as well (e.g. --snippet-module-path).

-- Jon

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20210126/5308df9a/attachment.htm>