lucaswerkmeister/javadoc2ceylondoc

A small Ceylon tool to convert javadoc to ceylondoc.

javadoc2ceylondoc

This tool converts javadoc-style comments into ceylondoc-style comments. Example:

Input:

/**
 * The best program ever
 *
 * well, if you’re a fan of programs that are too lazy for even a proper hello world, that is.
 */
shared void run() {
    print("hi");
}

Output:

"The best program ever
 
 well, if you’re a fan of programs that are too lazy for even a proper hello world, that is."
shared void run() {
    print("hi");
}

Processed elements

• @author → by
• @throws → throws
• @see → see
• {@link} → [[]]
• {@code} → ``
• HTML:
  • <b>: bold
  • <i>: italics
  • <tt>: monospaced
  • <p>: Markdown paragraphs

Usage

ceylon run herd.javadoc2ceylondoc inputFileName outputFileName

If inputFileName and/or outputFileName are missing, /dev/stdin and /dev/stdout are used instead, but special files aren’t (yet) supported by the Ceylon SDK (see ceylon/ceylon-sdk#121), so at the moment you can’t pipe code into javadoc2ceylondoc.

TODO

• @param → parameter doc

javadoc2ceylondoc's Issues

Remove @return tags?

Ceylon doc has no equivalent to @return tags, and I think that’s good, since most of my @returns tend to repeat or rephrase the first line of the main documentation. Should we remove them in javadoc2ceylondoc, or should we keep them?

Default output to input file instead of /dev/stdout?

This is probably what most people would expect, and by now the converter is probably stable enough that we can do this.

Read input file completely before writing to output file

If input file = output file, the result is empty.

Properly indent doc strings

see isn’t properly implemented

Java’s @see contains the parameter list:

/**
 * @see String#replace(CharSequence, CharSequence)
 */

We have to remove it. At the moment, we turn it into this:

see(`function String.replace(CharSequence,`)