Source/Javadoc links (was: Description of module file format?)

[Jesse Glick]

On 01/27/2012 10:49 AM, Reinier Zwitserloot wrote:
> Trivial to write size optimizer that strips sections out that aren't
> required to run the module.

For example, for deployment to an embedded device, or via JNLP or applet. I do not see any compelling reason to strip out optional sections for SE desktop deployment - 
disks are cheap these days. I agree that a well-defined location is critical, and including this information right in the jmod rather than a separate artifact is 
desirable for simplicity.

(OSGi defines the OSGI-OPT/ ZIP path prefix which it guarantees can be safely stripped out, but does not define more than that as far as I know.)

> being able to see the API documentation
> when using a library, or jump into the source either to just review how a
> third party library's code works or to allow the debugger to jump into a
> method call is a rather useful aspect

Yes, this is absolutely crucial for developer productivity when using third-party libraries - or even your own libraries that you just happen to be referencing by 
well-known version in the repository, rather than via collocation in a source checkout. I work on Maven support in NetBeans and I can say that automatic association of 
sources and Javadoc with a dependency (downloading them on demand in that case) is a key feature, one of the primary "pain points" when using something like plain Ant 
without a repository concept.

In my experience sources are much more important than Javadoc, so if package size is a concern dropping Javadoc but keeping sources would be reasonable. An IDE can 
essentially reconstruct Javadoc from source files during code completion anyway - and formatted appropriately for that tool rather than a web browser. You can always 
publish HTML Javadoc on your project site but once users start really writing code this is not likely to be the preferred medium. There are of course some subtleties in 
producing on-the-fly documentation:

1. The javadoc tool lets you decide which packages & classes, and which access levels, to document. I think this is superseded by the exports list of the module.

2. The tool lets you enable or disable display of @author and @version and the like. But an IDE (or other source-consuming tool) can just have a personal preference for 
displaying these.

3. HTML generation lets you link to other Javadoc sets. Probably superseded by the requires clause of the module: if sources are available for other libraries (or HTML 
Javadoc has been associated by some other means), then a tool can trivially link to them itself.

4. Custom doclets are probably inappropriate for general-purpose consumption, especially by a tool which may have its own specialized way of displaying library 
documentation to begin with.

5. Custom taglets are a more interesting case, since these would actually be specific to certain projects. How widely used are these? To what extent are these superseded 
by @Documented annotations? When they are not trivially replaced with an annotation, does it make sense to declare required taglets in module-info.java, so that they 
would both be run automatically by javadoc with special parameters, and interpretable by IDEs which wish to support this feature (running the taglet in a sandbox)? Custom 
-tag looks to be superseded by annotations.

6. Some libraries include custom content under doc-files/ subdirs, generally HTML pages and maybe some images. I suppose these could be preserved as is in the source 
section of a jmod.

7. Documentation written in a language other than English is uncommon but a consideration. If the only documentation - that written in source files itself - is in another 
language, then to reconstruct summary sentences properly you need to know to use the right BreakIterator. (If the primary documentation is in English but translated 
documentation is available separately, then probably nothing special needs to happen in the jmod: an IDE user can explicitly associate the translated documentation with 
the library.)