Posted by johncarl81 on
URL: https://discuss.asciidoctor.org/Export-Javadoc-strings-tp4172.html

The power of a community of tools is the ability to combine them in interesting and new ways.  Unfortunately, Asciidoclet does not play the the collaboration space very well as the end result is HTML.  Instead, what if we simply exported the javadocs to an annotated (tagged?) plain text file?  These files could them be incorporated into a larger documentation code base through the includes directive.

This certainly wasn't my idea, we've had a few requests for this feature on the Asciidoclet project:
https://github.com/asciidoctor/asciidoclet/issues/42

Tacking this feature on to Asciidoclet feels like a mistake though.  Asciidoclet does its focused job well and I don't want to muddy the scope with another wildly different feature.  With that in mind, I created a new doclet that simply exports the strings to plain text files.  I call it Outputdoclet:

https://github.com/johncarl81/outputdoclet

This repository is a stake in the ground and I'd appreciate input from the community.

Here's a few notes on the current functionality:

* We export .adoc files.  I chose to go this direction as the target is to collaborate with Asciidoctor tools.  Also, the files are annotated with the tag directive.

* Currently the entire javadoc raw string is exported.  This will include javadoc annotations, which may not be desired.  Here's an example:

/**
 * Method comment
 * @param options
 * @param errorReporter
 * @return blah
 */
@SuppressWarnings("UnusedDeclaration")
public static boolean validOptions(String[][] options, DocErrorReporter errorReporter) {
    return new StandardAdapter().validOptions(options, errorReporter);
}

outputs:

// tag::validOptions
Method comment
@param options
@param errorReporter
@return blah
// end::validOptions

We could parse the javadoc format deeper to export the javadoc comment, annotations, etc in separate tags, possibly along with the raw output as well.

*  The tag names need some work to fully match the method / class / field names and enforce uniqueness.

* The Outputdoclet project is owned by me on github.. should we transfer ownership to the larger Asciidoctor organization?

* I'm not married to the name Outputdoclet and I'd appreciate other name suggestions. ("There are only two hard things in Computer Science: cache invalidation and naming things.")

EDIT:  * I'm not sure how to chain doclets in a way to compose them together.  Currently this doclet stops regular javadoc or Asciidoclet doclets from running.  Is there a way to run multiple doclets?

Again, I'd love to hear everyone's thoughts.  Thanks!