Export Javadoc strings

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.")

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

---

If you reply to this email, your message will be added to the discussion below:

http://discuss.asciidoctor.org/Export-Javadoc-strings-tp4172.html

To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML

Sounds like a great idea, I think there have been some SO questions along this line too.

On Sunday, January 10, 2016, mojavelinux [via Asciidoctor :: Discussion] <[hidden email]> wrote:

I like the idea of having a separate exporter tool. That certainly embraces the proven unix philosophy: do one thing and do it well.

// tag::validOptions

This needs to have a trailing []. 

// tag::validOptions[]

>  I'm not married to the name Outputdoclet and I'd appreciate other name suggestions.

Is it processing the docstrings in anyway? If not, then I'd say the name fits, except I might go for "export" instead of "output". Perhaps Exportdoclet or even Extractdoclet.

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

Once we get a name nailed down and a first round of user testing, then certainly.

-Dan

On Sun, Jan 10, 2016 at 9:03 AM, johncarl81 [via Asciidoctor :: Discussion] <[hidden email]> wrote:

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.")

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

---

If you reply to this email, your message will be added to the discussion below:

http://discuss.asciidoctor.org/Export-Javadoc-strings-tp4172.html

To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML

--

Dan Allen | @mojavelinux | http://google.com/profiles/dan.j.allen

---

If you reply to this email, your message will be added to the discussion below:

http://discuss.asciidoctor.org/Export-Javadoc-strings-tp4172p4173.html

To start a new topic under Asciidoctor :: Discussion, email <a href="javascript:_e(%7B%7D,&#39;cvml&#39;,&#[hidden email]&#39;);" target="_blank">ml-node+s49171n1h37@...
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML

--
Sent from Gmail Mobile

---

If you reply to this email, your message will be added to the discussion below:

http://discuss.asciidoctor.org/Export-Javadoc-strings-tp4172p4174.html

To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML

Is this project any help:
____
dbdoclet is the implementation of a javadoc doclet, which converts javadoc documentation to DocBook XML. In addition to the generation of DocBook XML, it is able to create UML class diagrams.
The command line tool dbdoclet can be used directly to convert javadoc to DocBook. It's a simple wrapper around the javadoc tool and the javadoc doclet dbdoclet.jar.
The dbdoclet doclet jar archive is part of the maven central repository. Use GroupId: org.dbdoclet and ArtifactId: dbdoclet to add a dependency to your project.
dbdoclet is part of the dbdoclet suite of tools. For more information visit http://www.dbdoclet.org.
____

---

If you reply to this email, your message will be added to the discussion below:

http://discuss.asciidoctor.org/Export-Javadoc-strings-tp4172p4196.html

To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML