de.unkrig.commons.doclet.html

Class Html

java.lang.Object

de.unkrig.commons.doclet.html.Html

public class Html
extends java.lang.Object

Helper functionality in the context of doclets and HTML.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Html.ExternalJavadocsLinkMaker See the documentation of the '-linkoffline' option of the JAVADOC tool.
static interface	Html.LinkMaker When generating HTML from JAVADOC, this interface is used to generate links to JAVA elements.

Field Summary

Fields

Modifier and Type	Field and Description
static Html.LinkMaker	STANDARD_LINK_MAKER Implements the strategy of the standard JAVADOC doclet.

Constructor Summary

Constructors

Constructor and Description
Html(Html.LinkMaker linkMaker)

Method Summary

Modifier and Type	Method and Description
static java.lang.String	escapeSgmlEntities(java.lang.String text) Replaces "<", ">" and "&".
protected java.lang.String	expandTag(com.sun.javadoc.Doc ref, com.sun.javadoc.RootDoc rootDoc, java.lang.String tagName, java.lang.String argument) Expands a tag to HTML text.
java.lang.String	fromJavadocText(java.lang.String s, com.sun.javadoc.Doc ref, com.sun.javadoc.RootDoc rootDoc) Converts JAVADOC markup into HTML.
java.lang.String	fromTags(com.sun.javadoc.Tag[] tags, com.sun.javadoc.Doc ref, com.sun.javadoc.RootDoc rootDoc) Expands inline tags to HTML.
java.lang.String	generateFor(com.sun.javadoc.Doc doc, com.sun.javadoc.RootDoc rootDoc) Generates HTML markup for the given doc in the context of ref.
static com.sun.javadoc.Doc	hrefToDoc(java.lang.String href, com.sun.javadoc.RootDoc rootDoc, com.sun.javadoc.ClassDoc from)
java.lang.String	makeLink(com.sun.javadoc.Doc from, com.sun.javadoc.Doc to, boolean plain, java.lang.String label, java.lang.String target, com.sun.javadoc.RootDoc rootDoc)
java.lang.String	makeLink(com.sun.javadoc.Doc from, java.lang.String to, boolean plain, java.lang.String label, com.sun.javadoc.RootDoc rootDoc) Resolves a 'target specification' as in the "@link" tag.
java.lang.String	optionalTag(com.sun.javadoc.Doc doc, java.lang.String tagName, com.sun.javadoc.RootDoc rootDoc) Verifies that the named block tag exists at most once, replaces line breaks with spaces, and convert its text to HTML.
java.lang.String	optionalTag(com.sun.javadoc.Doc doc, java.lang.String tagName, java.lang.String defaulT, com.sun.javadoc.RootDoc rootDoc) Verifies that the named block tag exists at most once, replaces line breaks with spaces, and convert its text to HTML.

Methods inherited from class java.lang.Object

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

Field Detail

STANDARD_LINK_MAKER

public static final Html.LinkMaker STANDARD_LINK_MAKER

Implements the strategy of the standard JAVADOC doclet.

Hrefs are generated as follows:

Field, constructor or method of same class:

"#toField"

"#ToClass(java.lang.String)"

"#toMethod(java.lang.String)"

Class, field, constructor or method in external package:

"http://external.url/to/package/ToClass"

"http://external.url/to/package/ToClass#toField"

"http://external.url/to/package/ToClass#ToClass(java.lang.String)"

"http://external.url/to/package/ToClass#toMethod(java.lang.String)"

Class, field, constructor or method in same package:

"ToClass"

"ToClass#toField"

"ToClass#ToClass(String)"

"ToClass#toMethod(String)"

Class, field, constructor or method in different (but "included") package:

"../../to/package/ToClass"

"../../to/package/ToClass#toField"

"../../to/package/ToClass#ToClass(String)"

"../../to/package/ToClass#toMethod(String)"

Class, field or method in non-included package:

null

Default labels are generated as follows:

Field, constructor or method of same class:

"toField"

"ToClass(java.lang.String)"

"toMethod(java.lang.String)"

Class, or field, constructor or method in different class:

ToClass

ToClass.toField

ToClass(java.lang.String)

ToClass.toMethod(java.lang.String)

Constructor Detail

Html

public Html(Html.LinkMaker linkMaker)

Method Detail

fromTags

public java.lang.String fromTags(com.sun.javadoc.Tag[] tags,
                                 com.sun.javadoc.Doc ref,
                                 com.sun.javadoc.RootDoc rootDoc)
                          throws Longjump

Expands inline tags to HTML. Inline tags, as of Java 8, are:

   {@code text}
   {@docRoot}
   {@inheritDoc}
   {@link package.class#member label}
   {@linkplain package.class#member label}
   {@literal text}
   {@value package.class#field}
 

Only part of these are currently acceptable for the transformation into HTML.

Throws:

Longjump

fromJavadocText

public java.lang.String fromJavadocText(java.lang.String s,
                                        com.sun.javadoc.Doc ref,
                                        com.sun.javadoc.RootDoc rootDoc)
                                 throws Longjump

Converts JAVADOC markup into HTML.

Parameters:

ref - The 'current element'; relevant to resolve relative references

rootDoc - Used to resolve absolute references and to print errors and warnings

Throws:

Longjump

expandTag

protected java.lang.String expandTag(com.sun.javadoc.Doc ref,
                                     com.sun.javadoc.RootDoc rootDoc,
                                     java.lang.String tagName,
                                     @Nullable
                                     java.lang.String argument)
                              throws Longjump

Expands a tag to HTML text. Supported tags are:

Text

Expands to the literal text

{@code text}

Expands to the text, in monospace font and with HTML entities escaped

{@value field-ref}

Expands to the constant initializer value of the designated field

{@link ref [ text ] }

Expands to a link (in monospace font) to the designated ref

{@linkplain ref [ text ] }

Like {@ link}, but in default font

Subclasses may override this method to expand more than these tags.

Parameters:

argument - The text between the tag name and the closing brace, not including any leading space, or null iff there is no argument

Throws:

Longjump

hrefToDoc

public static com.sun.javadoc.Doc hrefToDoc(java.lang.String href,
                                            com.sun.javadoc.RootDoc rootDoc,
                                            com.sun.javadoc.ClassDoc from)
                                     throws Longjump

Parameters:

href - A link like "../../pkg/MyClass#myMethod(java.lang.String)"

from - The ClassDoc to which this link is relative to

Returns:

The package, class, field or method that the href designates

Throws:

Longjump

makeLink

public java.lang.String makeLink(com.sun.javadoc.Doc from,
                                 java.lang.String to,
                                 boolean plain,
                                 @Nullable
                                 java.lang.String label,
                                 com.sun.javadoc.RootDoc rootDoc)
                          throws Longjump

Resolves a 'target specification' as in the "@link" tag.

Example return values are:

#myMethod

<a href="#myMethod(java.lang.String)">myMethod(java.lang.String)</a>

(method in same class)

pkg.MyClass#myMethod(String)

<a href="../pkg/MyClass#myMethod(java.lang.String)">MyClass.myMethod(java.lang.String)</a>

("included" class)

java.net.Socket#close()

<a href="http://docs.oracle.com/javase/7/docs/api/java/net/Socket.html#close()">Socket.close()</a>

(class is not "included", but is contained in an "external package")

org.apache.tools.ant.Task#execute()

org.apache.tools.ant.Task.execute()

(class is neither "included" nor documented in an "external package")

Parameters:

from - The package, class or member currently being documented, or the rootDoc

to - E.g. "pkg.MyClass#myMethod(String)"

plain - Whether this is a "@linkplain"

label - The (optional) label to display in the link

Throws:

Longjump

makeLink

public java.lang.String makeLink(com.sun.javadoc.Doc from,
                                 com.sun.javadoc.Doc to,
                                 boolean plain,
                                 @Nullable
                                 java.lang.String label,
                                 @Nullable
                                 java.lang.String target,
                                 com.sun.javadoc.RootDoc rootDoc)
                          throws Longjump

Parameters:

plain - Whether this is a "@plainlink"

target - The value of the (optional) 'target="..."' attribute of the HTML anchor

Returns:

An HTML snippet like "<a href="#equals(java.lang.Object)">THE-LABEL</a>"

Throws:

Longjump

escapeSgmlEntities

public static java.lang.String escapeSgmlEntities(java.lang.String text)

Replaces "<", ">" and "&".

optionalTag

@Nullable
public java.lang.String optionalTag(com.sun.javadoc.Doc doc,
                                               java.lang.String tagName,
                                               com.sun.javadoc.RootDoc rootDoc)
                                        throws Longjump

Verifies that the named block tag exists at most once, replaces line breaks with spaces, and convert its text to HTML.

Returns:

null iff the tag does not exist

Throws:

Longjump

optionalTag

public java.lang.String optionalTag(com.sun.javadoc.Doc doc,
                                    java.lang.String tagName,
                                    java.lang.String defaulT,
                                    com.sun.javadoc.RootDoc rootDoc)
                             throws Longjump

Verifies that the named block tag exists at most once, replaces line breaks with spaces, and convert its text to HTML.

Returns:

defaulT iff the tag does not exist

Throws:

Longjump

generateFor

public java.lang.String generateFor(com.sun.javadoc.Doc doc,
                                    com.sun.javadoc.RootDoc rootDoc)
                             throws Longjump

Generates HTML markup for the given doc in the context of ref.

Throws:

Longjump