CODAVAJ

       _{codavaj is anadrome of javadoc}

Install

• https://jitpack.io/#umjammer/codavaj

Usage

Convert Javadoc to Java Source

to convert javadoc tree into java source
(external references to Sun's standard javadocs are automatically resolved i.e. http://java.sun.com/j2se/1.5.0/docs/api/)

codavaj.cmd codavaj <javadoc-dir> <javasource-dir> {<external-link-url>}*

i.e.

 $ # from LOCAL javadoc
 $ codavaj.cmd codavaj tmp/jumpi/javadoc tmp/jumpi/src
 $ # or from local javadoc w/ EXTERNAL LINK
 $ codavaj.cmd codavaj tmp/jumpi/javadoc tmp/jumpi/src http://external.link.com/api
 $ # or from REMOTE javadoc
 $ codavaj.cmd codavaj http://jumpi.sourceforge.net/javadoc/j2se tmp/jumpi/src

Cooperate with Java Parser

parser	set javadoc to (decompiled) source	rename argument names as javadoc documented	code	output
JavaParser	✅	🚫	📄	👑
rewrite	jdk version problem?	🚧	📄
JDT	✅	🚫	📄	little bit worse than JavaParser
spoon	✅	🚫	📄	formats are gone

Example

 $ # install codavaj
 $ cd $HOME/src/java
 $ git clone https://github.com/umjammer/codavaj

 $ # decompile by fernflower
 $ cd $HOME/src/java/javax-speech
 $ curl -o tmp/speech-1.0.0.jar https://github.com/umjammer/umjammer/raw/mvn-repo/javax/speech/speech/1.0.0/speech-1.0.0.jar
 $ mkdir -p tmp/classes
 $ java -jar fernflower.jar tmp/speech-1.0.0.jar tmp/classes
 $ pushd src/main/java; jar xvf $HOME/src/java/javax-speech/tmp/classes/speech-1.0.0.jar; popd 

 $ # add comment from javadoc on the net to decompiled source
 $ cd $HOME/src/java/javax-speech
 $ mkdir -p src/main/java
 $ mkdir -p tmp/src
 $ (pushd $HOME/src/java/codavaj; mvn -P comment test-compile antrun:run@javaParser \
   -Dcomment.javadoc=https://docs.oracle.com/cd/E17802_01/products/products/java-media/speech/forDevelopers/jsapi-doc \
   -Dcomment.source=$HOME/src/java/javax-speech/src/main/java \
   -Dcomment.out=$HOME/src/java/javax-speech/tmp/src \
   ; popd)
 $ diff -rBw src/main/java tmp/src | less -R
 $ diff -rBw src/main/java tmp/src > tmp/c.patch
 $ pushd src/main/java; patch -p 2 < ../../../tmp/c.patch; popd   

known issues

• codavaj does not introduce default constructor's if they weren't found in the javadoc. This leads to compile problems if there are subclasses which use the class's default constructor through the implicit super().

• nekohtml ~1.19.22

  • https://mvnrepository.com/artifact/net.sourceforge.nekohtml/nekohtml/1.9.22
    • https://mvnrepository.com/artifact/xerces/xercesImpl/2.11.0
  • but 1.19.22 doesn't work with this project currently
  • so i excluded xerces from dependencies, and add xerces 2.12.2 individually. idk how codeql detect those.
  • https://sourceforge.net/p/nekohtml/bugs/167/#fdcc

• @see split too much by arguments' separator ","

• override methods after 2nd.'s comment are gone

• h hags

• code tag

• ol, ul, li tag

References

• https://docs.openrewrite.org/

TODO

• javadoc 1.8
• javadoc html5
• javadoc 11
• en test case
• https://github.com/HtmlUnit/htmlunit-neko
  • https://github.com/HtmlUnit/htmlunit-neko/security/advisories/GHSA-6jmm-mp6w-4rrg TODO
• use vavi-util-screenscraping?
• interface default
• Spoon