Uncategorized

What’s Up, JavaDoc?

March 4, 2011   ·   By   ·   1 Comment   ·   Posted in Uncategorized

Dexy has two new filters, a “java” filter and a “javadocs” filter, which provide support for compiling and running Java files as well as incorporating JavaDoc comments and metadata into your documentation.

Here’s our Hello, World source code:

public class hello {
public static void main(String args[]) {
System.out.println("Hello, World!");
}
}

this gets compiled, then run, producing output like this:

Hello, World!

If the file is part of a package then you need to specify the fully qualified class name by passing a ‘main’ parameter in the .dexy file, you can see this in the .dexy file for this blog post:

{
  "hello.java|java" : {},
  "helloworld.java|java" : {
    "main" : "hello.helloworld"
  },
  "javadoc-data.json|javadocs" : {}
}

Here is the helloworld.java file:

package hello;

/**
* Class which says hello, world!
*/
public class helloworld {

public static String greeting_text = "Hello World";

/**
* Returns the text of a greeting.
*
* @returns greeting text
*/
public static String greeting () {
return greeting_text;
}

/**
* main method which calls the greeting method
*/
public static void main(String args[]) {
System.out.println(greeting());
}
}

And here is what it outputs:


Hello World

The JavaDoc support is made possible by a custom Doclet (source code on bitbucket). To run the Doclet use a command like this (or an equivalent ant command):

javadoc -doclet it.dexy.jsondoclet.Doclet -docletpath json-doclet.jar:json_simple-1.1.jar helloworld.java

You should then get a file named javadoc-data.json, which will look something like this:

{"packages":{"hello":{"classes":{"helloworld":{"methods":{"greeting":{"tags":{"
@returns":{"text":"greeting text","kind":"@returns"}},"source":"  public static
String greeting () {\n    return greeting_text;\n  }\n\n","comment-
text":"Returns the text of a greeting.","line-end":19,"lines":{"17":"
}","16":"    return greeting_text;","18":"","15":"  public static String
greeting () {"},"return-type":"java.lang.String","line-start":15,"raw-comment-
text":" Returns the text of a greeting.\n\n @returns greeting
text\n"},"main":{"tags":{},"source":"  public static void main(String args[])
{\n    System.out.println(greeting());\n  }\n}\n\n","comment-text":"main method
which calls the greeting method","23":"
System.out.println(greeting());","22":"  public static void main(String args[])
{","25":"}","24":"  }","lines":{},"return-type":"void","26":"","line-start":22
,"raw-comment-text":" main method which calls the greeting
method\n"}},"tags":{},"superclass":"java.lang.Object","comment-text":"Class
which says hello, world!","package":"hello","source-file":"helloworld.java
","qualified-name":"hello.helloworld","line-start":6,"fields":{"greeting_text
":{"comment-text":"","qualified-
name":"hello.helloworld.greeting_text","type":"java.lang.String"}}}},"comment-
text":""}}}

This JSON can of course be used for any purpose, but one nice purpose would be to feed it into a Dexy document. For now this is a separate step, mostly for simplicity. In the projects I have developed this for, I am using ant to generate the JSON within a Java project, then generating documentation with dexy (I run this via “ant && dexy”).

There is a ‘javadocs’ filter which, for now, applies syntax highlighting to the source code. It may do some more specialized processing later. Its use is optional but recommended. The jinja filter (in the document in which you wish to incorporate the javadoc output) will automatically load JSON into a hash for you, so you can access any of the elements (not all JavaDoc elements are supported yet, but please send an example if you want a particular one supported and this can be added very quickly).

So, as a quick example, here is a docstring for the greeting method:


Returns the text of a greeting.

and here is that method’s source code:

  public static String greeting () {
return greeting_text;
}

For a comprehensive example showing how to traverse the various JavaDoc elements, look at examples/doc.html in the json-doclet repository.

These new filters make it possible to write a far broader range of Java documentation, while not losing the benefits of the JavaDoc structure, and of course the huge wealth of existing JavaDoc documentation. Dexy’s philosophy is to make it easier to document every programming language, and to work with and make the most of existing tools. I look forward to people taking advantage of the fact that writing custom JavaDoc formats is now as easy as writing HTML with some templating tags, there’s no need to implement a Doclet in Java to customize the look and feel of JavaDoc output.

As with Dexy itself, this Doclet code is being actively developed so please check frequently to make sure you have the latest version.

One Comment
  1. Hmm. It’s almost as if you’re trying to promote JavaDoc.

    “ant && dexy” hahaha!