de.unkrig.commons.doclet.html

Class Html

java.lang.Object

de.unkrig.commons.doclet.html.Html

public class Html
extends 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 class	Html.Link Representation of a link in an HTML document.
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 String	escapeSgmlEntities(String text) Replaces "<", ">" and "&".
protected String	expandTag(com.sun.javadoc.Doc ref, com.sun.javadoc.RootDoc rootDoc, com.sun.javadoc.Tag tag) Expands a tag to HTML text.
String	fromTags(com.sun.javadoc.Tag[] tags, com.sun.javadoc.Doc ref, com.sun.javadoc.RootDoc rootDoc) Expands inline tags to HTML.
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(String href, com.sun.javadoc.RootDoc rootDoc, com.sun.javadoc.ClassDoc from)
String	makeLink(com.sun.javadoc.Doc from, com.sun.javadoc.Doc to, boolean plain, String label, String target, com.sun.javadoc.RootDoc rootDoc)
String	optionalTag(com.sun.javadoc.Doc doc, 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.
String	summaryDescription(com.sun.javadoc.Doc doc, com.sun.javadoc.RootDoc rootDoc)
static com.sun.javadoc.Doc	targetOfSeeTag(com.sun.javadoc.SeeTag seeTag)

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

RootDoc:

"../../"

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 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

expandTag

protected String expandTag(com.sun.javadoc.Doc ref,
                           com.sun.javadoc.RootDoc rootDoc,
                           com.sun.javadoc.Tag tag)
                    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

{@literal text}

Expands to the text, 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:

tag - The tag to expand

Returns:

The text resulting from the expansion, typically an HTML link

Throws:

Longjump

targetOfSeeTag

@Nullable
public static com.sun.javadoc.Doc targetOfSeeTag(com.sun.javadoc.SeeTag seeTag)

Returns:

A MemberDoc, ClassDoc, PackageDoc, or null

hrefToDoc

public static com.sun.javadoc.Doc hrefToDoc(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 String makeLink(com.sun.javadoc.Doc from,
                       com.sun.javadoc.Doc to,
                       boolean plain,
                       @Nullable
                       String label,
                       @Nullable
                       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 String escapeSgmlEntities(String text)

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

optionalTag

@Nullable
public String optionalTag(com.sun.javadoc.Doc doc,
                                     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

generateFor

public 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

summaryDescription

public String summaryDescription(com.sun.javadoc.Doc doc,
                                 com.sun.javadoc.RootDoc rootDoc)

Returns:

The "description" text for a javadoc-ish summary table; composed from the first sentence of the doc comment and its (optional) "@deprecated" tags