Starting to think about this some more. At least I have some idea what I don’t want, an HTML doc that gets stuffed into the Javadoc, somewhere under
doc-files. Although I could integrate the links into the body of the generated Javadoc, the generated HTML doc cannot link back, as it never gets processed as Javadoc. I end up with non-hyperlinked passages like:
When the connection result handler gets a connection, your application can pass result handlers for other operations using methods on the connection named
*Async(). For most operations, your application implements
ResultHandler. For searches, your application implements
SearchResultHandler. The result handler is notified upon completion of the operation.
Asynchronous methods are non-blocking, returning a
get()method lets you retrieve the result. Your application must coordinate concurrency when you use asynchronous operations. See
SearchAsync.javafor an example.
All those interfaces, files, and methods, and nowhere to go.
Furthermore, the structure of the dev guide is linear so far. Probably need to cut the pieces up instead, and look at where to add them if they’re rewritten as Javadoc comments. For example, the section on the Assertion request control might well sit at the top of the generated AssertionRequestControl page.