[BUILD-200] Introduce asciidoc for Javadoc Created: 16/Mar/15  Updated: 07/Jul/16  Resolved: 04/May/15

Status: Closed
Project: Build
Component/s: None
Affects Version/s: None
Fix Version/s: POMs 31

Type: New Feature Priority: Major
Reporter: Magnolia International Assignee: Magnolia International
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Attachments: File ConvertJavadocToAsciiDoc.groovy    
Issue Links:
causality
is causing BUILD-238 Cannot build main (5.3) on Java 6 Closed
relation
is related to BUILD-79 Examples in CMS taglib reference unre... Open
is related to BUILD-209 Update javadoc plugin to 2.10.3 Closed
is related to BUILD-195 Disable doclint for javadoc (Cannot b... Closed
Template:
Acceptance criteria:
Empty

 Description   

See

This is also related to BUILD-195; if we do this and/or disable doclint for javadoc, we need to decide if/how we migrate existing javadoc that uses html.



 Comments   
Comment by Magnolia International [ 16/Mar/15 ]

This works neatly, but unfortunately is not lenient towards existing html-based javadocs.
I raised an issue with the Asciidoctor people, let's see what happens: https://github.com/asciidoctor/asciidoclet/issues/40
(we can either mass-convert our existing docs if we find an appropriate tool (which would need to be javadoc aware .. yikes), or provide a fix for the issue in question, if detecting the presence of html in a javadoc comment is safe enough (i.e I doubt it is completely safe, since one might in fact HAVE html in their Asciidoc, e.g code samples)

Comment by Magnolia International [ 17/Mar/15 ]

Suggestions by johncarl81 are very good. I'm thinking:

  • a flag on a per-project basis to enable the doclet
  • a script to mass-convert existing javadoc for those projects.
Comment by Magnolia International [ 17/Mar/15 ]

This script can be used, e.g:
groovy ConvertJavadocToAsciiDoc.groovy ~/Dev/magnolia/git/magnolia_main/magnolia-core

Comment by Magnolia International [ 17/Mar/15 ]

And we could apply this patch to enable projects to opt-out (I'd rather opt-in, but once more Maven's lack of the simplest boolean logic in properties doesn't make it possible)

diff --git a/poms/super-pom/pom.xml b/poms/super-pom/pom.xml
index 5f79dca..fb0a5b8 100644
--- a/poms/super-pom/pom.xml
+++ b/poms/super-pom/pom.xml
@@ -57,6 +57,8 @@
          to reconfigure said plugins.
      -->
     <skipTestJar>true</skipTestJar>
+    <!-- Set to empty to use the standard Javadoc Doclet -->
+    <javadocDocletClass>org.asciidoctor.Asciidoclet</javadocDocletClass>
   </properties>
 
   <build>
@@ -144,6 +146,12 @@
           <configuration>
             <detectOfflineLinks>false</detectOfflineLinks>
             <detectLinks>false</detectLinks>
+            <doclet>${javadocDocletClass}</doclet>
+            <docletArtifact>
+              <groupId>org.asciidoctor</groupId>
+              <artifactId>asciidoclet</artifactId>
+              <version>1.5.2</version>
+            </docletArtifact>
           </configuration>
         </plugin>
         <plugin>
Comment by Magnolia International [ 18/Mar/15 ]

Needs validation - do we all want this ?

Comment by Magnolia International [ 18/Mar/15 ]

Alternative proposal: in projects, pick which one you want:

  <properties>
    <javadocDoclet>${standardDoclet}</javadocDoclet>
  </properties>

or

  <properties>
    <javadocDoclet>${asciidocDoclet}</javadocDoclet>
  </properties>
Comment by Magnolia International [ 04/May/15 ]

Default is kept to standard doclet. Projects can explicitely use either:

  <properties>
    <javadocDoclet>${standardDoclet}</javadocDoclet>
  </properties>

or

  <properties>
    <javadocDoclet>${asciidocDoclet}</javadocDoclet>
  </properties>
Generated at Sun Feb 11 23:39:43 CET 2024 using Jira 9.4.2#940002-sha1:46d1a51de284217efdcb32434eab47a99af2938b.