Mixed traditional and Asciidoclet javadoc markup

In Hibernate we are trying to migrate to using Asciidoclet to author Javadoc. However, as Hibernate is a huge project it is simply not feasible to convert all of the docs at once so we have been working on a phased approach change pieces at a time such that we end up with a mix of traditional and Asciidoclet javadoc markup within the same project.

But in practice this has led to problems rendering the javadocs. If we enable Asciidoclet it messes up some of the traditional Javadoc markup; e.g. it escapes and “passes through” all HTML tags (you literally end up with <p/>, <li>, etc in the rendered HTML output). And if we disable Asciidoclet, of course the standard doclet butchers the Asciidoctor markup.

Are we missing something here? Does a project have to use one or the other approach? If so, that is severely limiting for larger projects to move to Asciidoclet

[johncarl81]

@mojavelinux, @msgilligan: it might be early as we haven’t gotten feedback, but would you review https://github.com/asciidoctor/asciidoclet/pull/91 and merge?

@sebersole, @gsmet: have you been able to use this feature, and, if so, does it meet your needs?

[johncarl81]

Yes, that’s right @mojavelinux - it’s only useful when a class is excluded from being processed. For instance, we can either explicitly include classes for processing or exclude classes from processing, the resulting classes not processed can finally be added back into the set being processed by adding the @asciidoclet javadoc tag.