Option to export AsciiDoc doc strings

[mojavelinux]

One of the attendees at Devoxx France proposed the idea of having an option in Asciidoclet to export all AsciiDoc doc strings to disk (i.e., export-docstrings). Exporting the strings would allow the content to be reused in other context or by other tools.

I really like this idea as a way to keep content DRY, especially if Javadoc is being treated as the canonical source of information for a portion of the documentation. It's the inverse strategy to using the include tag.

I imagine that each doc string would be exported to a file that is named according to where the doc string originated (package name + [class name] + [method name]). These files would be exported to the build output adjacent to the javadoc directory.

[johncarl81]

I think this would be easy to accomplish, but I'll need to investigate a bit. Great suggestion. I'll take a look soon. Thanks!

[johncarl81]

This gets a little hairy in the javadoc details. For example, we append javadoc comments and the tags within the comments. There are a number of routes we could go...

First, we could write a whole new doclet that just strips out the javadoc comments to a file. This would keep the scope of Asciidoclet small and allow for other source formats to be handled. The drawback of this would be javadoc syntax would also be included and would have to be parsed out if another tool was to use the output (we probably couldn't feed the output in to Asciidoctor directly).

Second, we could write out every block, tag, etc as a different file. This would be pretty verbose, but would allow a lot of flexibility. Would we write each tag as a separate file? In that case we may have to have some sort of incremental unique file name to avoid collisions.

Thoughts?

[mojavelinux]

we could write a whole new doclet that just strips out the javadoc comments to a file.

I think that's totally acceptable. So long as there is some way to invoke the command, I don't think the user is too worried about how it is done. Users may even want to do this in a separate step.

The drawback of this would be javadoc syntax would also be included and would have to be parsed out if another tool was to use the output (we probably couldn't feed the output in to Asciidoctor directly).

I think that's acceptable to start. After all, it is an export, so likely it will be used at the front of another pipeline which could deal with this cleanup.

Second, we could write out every block, tag, etc as a different file.

I think just exporting the class, interface and method blocks at first is sufficient. We could consider exporting all the blocks from a single source file to a single AsciiDoc file and use the tagging mechanism to allow the parts to be consumed individually.

For example:

// tag::method-name[]
JavaDoc source from method name.
// end::method-name[]

[dridi]

Thoughts?

I'm just starting playing with Asciidoctor, but I'm already finding it many incentives. One thing that bothers me though, is the javadoc integration. It's the same with Maven sites, javadoc(1) does its own thing and it doesn't integrate with the rest of the documentation. So of course only in an ideal world could I get my whole javadoc generated and well integrated into my overall documentation.

First thing I did after finding this thread was looking at the manual (did I mention I have also no knowledge wrt doclets?) and there I saw that it is actually meant to allow such a thing.

From javadoc(1):

You can modify or make a subclass of the standard doclet, or write your own doclet to generate HTML, XML, MIF, RTF or whatever output format you want.

From Doclet's javadoc:

If the doclet takes command line options, it must also implement optionLength and validOptions.

So I'm thinking instead that the doclet could accept a new command-line parameter to change the output from html to adoc. But it also means doing much much more, since it'd need to render whole pages, and not simply translate the asciidoc from doc comments (otoh the latter would be left untouched).

My uninformed 2 cents

[AlexanderZobkov]

Ideally it would be great to implement a doclet that allows to generate javadoc in asciidoc format (like mif-doclet by Sun) so that it can be integrated into this or that document prepared with using asciidoc and later converted to PDF. So far, it's only possible to achive by using series of complex transformation pipe, like: xml-doclet->xslt->asciidoc.

[johncarl81]

I've started a new project to output the raw contents of Javadocs to files. This can be used as part of the toolchain to incorporate the javadocs from a project into the final documentation.

You can find this project here: https://github.com/johncarl81/outputdoclet I figure we should continue this discussion about requirements and capabilities there.

[mojavelinux]

Very cool! You might want to announce this one on the list too.

[manoelcampos]

Hello @johncarl81 and @mojavelinux,

Is there any update on this issue? Because there is no discussion at the outputdoclet project page.

Thank you.

[johncarl81]

We really haven't focused on this capability. the export doclet project should be functional, but may need some further work to really work. I encourage you to give it a try and let us know what your experience is.

[manoelcampos]

Hello @johncarl81 ,

I'll take a look and let you know. Thank you.

[manoelcampos]

Hello again @johncarl81,

I think that this pull request is a good start point. We can continue the discussion there.