net.cscott.jdoctest
Class JDoctest

java.lang.Object
  net.cscott.jdoctest.JDoctest

All Implemented Interfaces:

com.sun.tools.doclets.Taglet

public class JDoctest
extends Object
implements com.sun.tools.doclets.Taglet

JDoctest implementing doctests via a @doc.test taglet. This tag can be used in any kind of Doc. It is not an inline tag. A "@doc.test" tag specifies an interactive javascript session, in an environment where the class' package has been imported. The output of the javascript session should match the output provided.

Author:

C. Scott Ananian

Tests:

This is an example of a test which passes:

js> "a".equals("a")
true

(EXPECT FAIL) This is an example of a test which fails:

js> 1+2
5

doctest failure running:
 1+2
expected: 
5
actual: 
3
 (JDoctest.java#80)

We can write tests which expect exceptions to be thrown, although it's a little clunky (implementing doctest.ELLIPSIS or doctest.IGNORE_EXCEPTION_DETAIL would make this nicer):

js> try {
  >   java.lang.String("hi").charAt(3);
  > } catch (e) {
  >   print(e.javaException.getMessage())
  > }
String index out of range: 3

This demonstrates that the current package has been imported:

js> JDoctest
[JavaClass net.cscott.jdoctest.JDoctest]
js> Version.PACKAGE_NAME
jdoctest

Note that results referencing object hashes are properly handled in the output comparison function, even when Rhino gives a different hash at runtime:

js> o = new java.lang.Object()
java.lang.Object@1d2068d
js> o
java.lang.Object@1d2068d
js> new java.lang.Object()
java.lang.Object@1ac2f9c

Constructor Summary

JDoctest()

Method Summary

String	getName() Return the name of this custom tag.
boolean	inConstructor() Will return true since @doc.test can be used in constructor documentation.
boolean	inField() Will return true since @doc.test can be used in field documentation.
boolean	inMethod() Will return true since @doc.test can be used in method documentation.
boolean	inOverview() Will return true since @doc.test can be used in method documentation.
boolean	inPackage() Will return true since @doc.test can be used in package documentation.
boolean	inType() Will return true since @doc.test can be used in type documentation (classes or interfaces).
boolean	isInlineTag() Will return false since @doc.test is not an inline tag.
static void	register(Map tagletMap) Register this Taglet.
String	toString(Tag tag) Given the Tag representation of this custom tag, return its string representation.
String	toString(Tag[] tags) Given an array of Tags representing this custom tag, return its string representation.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

JDoctest

public JDoctest()

Method Detail

getName

public String getName()

Return the name of this custom tag.

Specified by:

getName in interface com.sun.tools.doclets.Taglet

Tests:

js> new JDoctest().getName()
doc.test

inField

public boolean inField()

Will return true since @doc.test can be used in field documentation.

Specified by:

inField in interface com.sun.tools.doclets.Taglet

inConstructor

public boolean inConstructor()

Will return true since @doc.test can be used in constructor documentation.

Specified by:

inConstructor in interface com.sun.tools.doclets.Taglet

inMethod

public boolean inMethod()

Will return true since @doc.test can be used in method documentation.

Specified by:

inMethod in interface com.sun.tools.doclets.Taglet

inOverview

public boolean inOverview()

Will return true since @doc.test can be used in method documentation.

Specified by:

inOverview in interface com.sun.tools.doclets.Taglet

inPackage

public boolean inPackage()

Will return true since @doc.test can be used in package documentation.

Specified by:

inPackage in interface com.sun.tools.doclets.Taglet

inType

public boolean inType()

Will return true since @doc.test can be used in type documentation (classes or interfaces).

Specified by:

inType in interface com.sun.tools.doclets.Taglet

isInlineTag

public boolean isInlineTag()

Will return false since @doc.test is not an inline tag.

Specified by:

isInlineTag in interface com.sun.tools.doclets.Taglet

register

public static void register(Map tagletMap)

Register this Taglet.

Parameters:

tagletMap - the map to register this tag to.

Tests:

js> m = java.util.HashMap()
{}
js> JDoctest.register(m)
js> m.get("doc.test")
net.cscott.jdoctest.JDoctest@de1b8a

toString

public String toString(Tag tag)

Given the Tag representation of this custom tag, return its string representation.

Specified by:

toString in interface com.sun.tools.doclets.Taglet

Parameters:

tag - the Tag representation of this custom tag.

toString

public String toString(Tag[] tags)

Given an array of Tags representing this custom tag, return its string representation.

Specified by:

toString in interface com.sun.tools.doclets.Taglet

Parameters:

tags - the array of Tags representing of this custom tag.