Modifier and Type	Class and Description
private static class	MarkdownTransformer.AutoRefInlineParserFactory An `InlineParserFactory` that checks any unresolved link references in reference links.
private static class	MarkdownTransformer.DCTransformer
private static class	MarkdownTransformer.Lower A visitor to scan a Markdown document looking for any constructs that should be mapped to doc comment nodes.

Modifier and Type	Field and Description
private static final DocTreeVisitor<Boolean, Void>	isMarkdownVisitor A fast scanner for detecting Markdown nodes in documentation comment nodes.
private static final char	PLACEHOLDER

Access	Constructor and Description
public	MarkdownTransformer() Public no-args constructor, suitable for use with `java.util.ServiceLoader`.

Modifier and Type	Method and Description
private boolean	isMarkdown(DocCommentTree node)
public String	name() Implements com.sun.tools.javac.api.JavacTrees.DocCommentTreeTransformer.name. Returns the name of this transformer.
public DocCommentTree	transform(DocTrees trees, DocCommentTree tree) Implements com.sun.tools.javac.api.JavacTrees.DocCommentTreeTransformer.transform. Transforms a documentation comment tree.

isMarkdownVisitor	back to summary
private static final DocTreeVisitor<Boolean, Void> isMarkdownVisitor A fast scanner for detecting Markdown nodes in documentation comment nodes. The scanner returns as soon as any Markdown node is found.

PLACEHOLDER	back to summary
private static final char PLACEHOLDER

MarkdownTransformer	back to summary
public MarkdownTransformer() Public no-args constructor, suitable for use with `java.util.ServiceLoader`.

isMarkdown	back to summary
private boolean isMarkdown(DocCommentTree node)

name	back to summary
public String name() Implements com.sun.tools.javac.api.JavacTrees.DocCommentTreeTransformer.name. Doc from com.sun.tools.javac.api.JavacTrees.DocCommentTreeTransformer.name. Returns the name of this transformer.

transform	back to summary
public DocCommentTree transform(DocTrees trees, DocCommentTree tree) Implements com.sun.tools.javac.api.JavacTrees.DocCommentTreeTransformer.transform. Doc from com.sun.tools.javac.api.JavacTrees.DocCommentTreeTransformer.transform. Transforms a documentation comment tree. Annotations @Override @DefinedBy:COMPILER_TREE

private Class MarkdownTransformer.AutoRefInlineParserFactory

Class Inheritance

extends Object
implements InlineParserFactory

java.lang.Object
jdk.internal.markdown.MarkdownTransformer.AutoRefInlineParserFactory

All Implemented Interfaces

jdk.internal.org.commonmark.parser.InlineParserFactory

An InlineParserFactory that checks any unresolved link references in reference links. If an unresolved link reference appears to be a reference to a program element, such as may be used in @see ... or {@link ...} tags, it generates a synthetic LinkReferenceDefinition. The reference is not validated to ensure it refers to any existing element. The primary function of this InlineParserFactory is to provide a custom implementation of an InlineParserContext via the create(InlineParserContext inlineParserContext) method. It is this InlineParserContext that actually manages the set of link reference definitions. This InlineParserFactory is intended to be registered with a Parser.Builder using setInlineParserFactory.

Field Summary

Modifier and Type	Field and Description
private final String	autorefScheme
private final ReferenceParser	refParser

Constructor Summary

Access	Constructor and Description
pack-priv	AutoRefInlineParserFactory(ReferenceParser refParser, String autorefScheme)

Method Summary

Modifier and Type	Method and Description
public InlineParser	Returns: the `InlineParser` create(InlineParserContext the standard `InlineParserContext` inlineParserContext) Implements jdk.internal.org.commonmark.parser.InlineParserFactory.create. Creates a parser with a modified `InlineParserContext` that delegates to the standard `InlineParserContext` and also checks unresolved link references.
private boolean	Returns: whether a string appears to be a reference to a program element isReference(String the string s) Returns whether a string appears to be a reference to a program element.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

autorefScheme	back to summary
private final String autorefScheme

refParser	back to summary
private final ReferenceParser refParser

Constructor Detail

AutoRefInlineParserFactory	back to summary
pack-priv AutoRefInlineParserFactory(ReferenceParser refParser, String autorefScheme)

Method Detail

create back to summary

create	back to summary
public InlineParser create(InlineParserContext inlineParserContext) Implements jdk.internal.org.commonmark.parser.InlineParserFactory.create. Creates a parser with a modified `InlineParserContext` that delegates to the standard `InlineParserContext` and also checks unresolved link references. Parameters inlineParserContext:InlineParserContext the standard `InlineParserContext` Returns:InlineParser the `InlineParser` Annotations @Override

public InlineParser create(InlineParserContext inlineParserContext)

Implements jdk.internal.org.commonmark.parser.InlineParserFactory.create.

Creates a parser with a modified InlineParserContext that delegates to the standard InlineParserContext and also checks unresolved link references.

Parameters

inlineParserContext:InlineParserContext: the standard InlineParserContext

Returns:InlineParser

the InlineParser

Annotations

@Override

isReference	back to summary
private boolean isReference(String s) Returns whether a string appears to be a reference to a program element. Parameters s:String the string Returns:boolean whether a string appears to be a reference to a program element

isReference

back to summary

private boolean isReference(String s)

Returns whether a string appears to be a reference to a program element.

Parameters

s:String: the string

Returns:boolean

whether a string appears to be a reference to a program element

jdk.internal.markdown back to summary

private Class MarkdownTransformer.DCTransformer

Class Inheritance

extends Object

java.lang.Object
jdk.internal.markdown.MarkdownTransformer.DCTransformer

Field Summary

Modifier and Type	Field and Description
private final String	autorefScheme
private final DocTreeMaker	m
private final ReferenceParser	refParser

Constructor Summary

Access	Constructor and Description
pack-priv	DCTransformer(JavacTrees t)

Method Summary

Modifier and Type	Method and Description
private static < the type of the items T extends DocTree> boolean	Returns: `true` if the items are reference-equal, and `false` otherwise equal(T the first item item1, T the second item item2) Shallow "equals" for two doc tree nodes.
private static < the type of the items T extends DocTree> boolean	Returns: `true` if the items are reference-equal, and `false` otherwise equal(List<? extends T> the first item list1, List<? extends T> the second item list2) Shallow "equals" for two lists of doc tree nodes.
public DCTree	Returns: a tree with any "extensions" converted into tags transform(DCTree the tree node tree) Transforms a doc tree node.
private List<? extends DCTree>	Returns: the transformed list transform(List<? extends DCTree> the list of tree nodes to be transformed trees) Transforms a list of doc tree nodes.
private DCTree.DCAuthor	transform(DCTree.DCAuthor tree)
private DCTree.DCDeprecated	transform(DCTree.DCDeprecated tree)
public DCTree.DCDocComment	transform(DCTree.DCDocComment tree)
private DCTree.DCHidden	transform(DCTree.DCHidden tree)
private DCTree.DCIndex	transform(DCTree.DCIndex tree)
private DCTree.DCLink	transform(DCTree.DCLink tree)
private DCTree.DCParam	transform(DCTree.DCParam tree)
private DCTree.DCProvides	transform(DCTree.DCProvides tree)
private DCTree.DCReturn	transform(DCTree.DCReturn tree)
private DCTree.DCSee	transform(DCTree.DCSee tree)
private DCTree.DCSerial	transform(DCTree.DCSerial tree)
private DCTree.DCSerialData	transform(DCTree.DCSerialData tree)
private DCTree.DCSerialField	transform(DCTree.DCSerialField tree)
pack-priv DCTree.DCSince	transform(DCTree.DCSince tree)
private DCTree.DCSpec	transform(DCTree.DCSpec tree)
private DCTree.DCSummary	transform(DCTree.DCSummary tree)
private DCTree.DCThrows	transform(DCTree.DCThrows tree)
private DCTree.DCUnknownBlockTag	transform(DCTree.DCUnknownBlockTag tree)
private DCTree.DCUnknownInlineTag	transform(DCTree.DCUnknownInlineTag tree)
private DCTree.DCUses	transform(DCTree.DCUses tree)
private DCTree.DCVersion	transform(DCTree.DCVersion tree)

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

autorefScheme	back to summary
private final String autorefScheme

m	back to summary
private final DocTreeMaker m

refParser	back to summary
private final ReferenceParser refParser

Constructor Detail

DCTransformer	back to summary
pack-priv DCTransformer(JavacTrees t)

Method Detail

equal back to summary

equal	back to summary
private static <T extends DocTree> boolean equal(T item1, T item2) Shallow "equals" for two doc tree nodes. Parameters <T> the type of the items item1:T the first item item2:T the second item Returns:boolean `true` if the items are reference-equal, and `false` otherwise

private static <T extends DocTree> boolean equal(T item1, T item2)

Shallow "equals" for two doc tree nodes.

Parameters

<T>: the type of the items
item1:T: the first item
item2:T: the second item

Returns:boolean

true if the items are reference-equal, and false otherwise

equal back to summary

equal	back to summary
private static <T extends DocTree> boolean equal(List<? extends T> list1, List<? extends T> list2) Shallow "equals" for two lists of doc tree nodes. Parameters <T> the type of the items list1:List<? extends T> the first item list2:List<? extends T> the second item Returns:boolean `true` if the items are reference-equal, and `false` otherwise

private static <T extends DocTree> boolean equal(List<? extends T> list1, List<? extends T> list2)

Shallow "equals" for two lists of doc tree nodes.

Parameters

<T>: the type of the items
list1:List<? extends T>: the first item
list2:List<? extends T>: the second item

Returns:boolean

true if the items are reference-equal, and false otherwise

transform	back to summary
public DCTree transform(DCTree tree) Transforms a doc tree node. This node dispatches to a more specific overload, based on the kind of the node. The result may be the same as the argument if no transformations were made. Parameters tree:DCTree the tree node Returns:DCTree a tree with any "extensions" converted into tags

transform

back to summary

public DCTree transform(DCTree tree)

Transforms a doc tree node. This node dispatches to a more specific overload, based on the kind of the node. The result may be the same as the argument if no transformations were made.

Parameters

tree:DCTree: the tree node

Returns:DCTree

a tree with any "extensions" converted into tags

transform	back to summary
private List<? extends DCTree> transform(List<? extends DCTree> trees) Transforms a list of doc tree nodes. If any of the nodes contain Markdown, the Markdown source is parsed and analyzed for any transformations. Any non-Markdown nodes are individually transformed. Parameters trees:List<? extends DCTree> the list of tree nodes to be transformed Returns:List<? extends DCTree> the transformed list

transform

back to summary

private List<? extends DCTree> transform(List<? extends DCTree> trees)

Transforms a list of doc tree nodes. If any of the nodes contain Markdown, the Markdown source is parsed and analyzed for any transformations. Any non-Markdown nodes are individually transformed.

Parameters

trees:List<? extends DCTree>: the list of tree nodes to be transformed

Returns:List<? extends DCTree>

the transformed list

transform	back to summary
private DCTree.DCAuthor transform(DCTree.DCAuthor tree)

transform	back to summary
private DCTree.DCDeprecated transform(DCTree.DCDeprecated tree)

transform	back to summary
public DCTree.DCDocComment transform(DCTree.DCDocComment tree)

transform	back to summary
private DCTree.DCHidden transform(DCTree.DCHidden tree)

transform	back to summary
private DCTree.DCIndex transform(DCTree.DCIndex tree)

transform	back to summary
private DCTree.DCLink transform(DCTree.DCLink tree)

transform	back to summary
private DCTree.DCParam transform(DCTree.DCParam tree)

transform	back to summary
private DCTree.DCProvides transform(DCTree.DCProvides tree)

transform	back to summary
private DCTree.DCReturn transform(DCTree.DCReturn tree)

transform	back to summary
private DCTree.DCSee transform(DCTree.DCSee tree)

transform	back to summary
private DCTree.DCSerial transform(DCTree.DCSerial tree)

transform	back to summary
private DCTree.DCSerialData transform(DCTree.DCSerialData tree)

transform	back to summary
private DCTree.DCSerialField transform(DCTree.DCSerialField tree)

transform	back to summary
pack-priv DCTree.DCSince transform(DCTree.DCSince tree)

transform	back to summary
private DCTree.DCSpec transform(DCTree.DCSpec tree)

transform	back to summary
private DCTree.DCSummary transform(DCTree.DCSummary tree)

transform	back to summary
private DCTree.DCThrows transform(DCTree.DCThrows tree)

transform	back to summary
private DCTree.DCUnknownBlockTag transform(DCTree.DCUnknownBlockTag tree)

transform	back to summary
private DCTree.DCUnknownInlineTag transform(DCTree.DCUnknownInlineTag tree)

transform	back to summary
private DCTree.DCUses transform(DCTree.DCUses tree)

transform	back to summary
private DCTree.DCVersion transform(DCTree.DCVersion tree)

jdk.internal.markdown back to summary

private Class MarkdownTransformer.Lower

Class Inheritance

extends AbstractVisitor

java.lang.Object
jdk.internal.org.commonmark.node.AbstractVisitor
jdk.internal.markdown.MarkdownTransformer.Lower

A visitor to scan a Markdown document looking for any constructs that should be mapped to doc comment nodes. The intended use is as follows:

Lower v = new Lower(document, source, replacements);
document.accept(v);
var result = v.getTrees();

On coordinates ... There are various position/coordinate systems in play in this code: 1. Tree positions, which correspond to positions in the original comment, represented as a 0-based character offset within the content of the comment. 2. Positions in the source string given to the Markdown parser, represented as a 0-based character offset within the source string. These differ from positions in the original comment if the source string contains U+FFFC characters representing embedded tree nodes. 3. Positions in the source string given to the Markdown parser, represented as (line, column) values within SourceSpan nodes. Both line and column are 0-based.

Note

SourceSpan objects never include newline characters. See Lower#toSourcePos(int, int) to convert from (line, column) coordinates to a source position. See Lower#sourcePosToTreePos(int) to convert from a source position to a position in the original comment, for use in tree nodes.

Field Summary

Modifier and Type	Field and Description
private final String	autorefScheme
private int	copyStartPos The start of source text to be copied literally when required.
private final Node	document The Markdown document being processed.
private static final Pattern	lineBreak The pattern for a line break.
private final DocTreeMaker	m
private int	mainStartPos The initial position in the enclosing comment of the source being transformed.
private static final int[]	NOSPAN
private int	replaceAdjustPos The current adjustment from positions in `source` to positions in the original comment, as used in doc tree nodes.
private final Iterator<?>	replaceIter An iterator containing the values to be substituted into the generated tree when U+FFFC characters are encountered in the document.
private final String	source The source for the Markdown document being processed.
private final int[]	sourceLineOffsets An array giving the position of the first character after each newline in the source.
private final StringBuilder	text The source text being accumulated, prior to being placed in a Markdown source node (`RawTextTree` with kind `MARKDOWN`).
private List<DCTree>	trees The list of trees being built.

Constructor Summary

Access

Constructor and Description

public

Lower(DocTreeMaker docTreeMaker, Node

the document to be converted

document, String

the source of the document to be converted

source, int

the position in the enclosing comment of the source to be converted

sourcePos, List<?>

the objects to be substituted when U+FFFC is encountered

replacements, String

the scheme used for auto-generated references

autorefScheme)

Creates an instance of the visitor, given a document, the source text for the document and objects to be substituted when U+FFFC characters are encountered.

Method Summary

Modifier and Type	Method and Description
private void	copyTo(int the end position endPos) Copies source text from the saved copy-start position to the given end position using the saved `source`, to the list of `trees`.
private void	flushText(int pos) Flushes any text in the `text` buffer, by creating a new Markdown source text node and adding it to the list of trees.
private int	Returns: the end of this node, from the end of the last span getEndPos(Node the node node) Returns the end of this node, from the end of the last span.
private int[]	Returns: the position in the source for the reference in a link getRefSpan(String the reference to find ref, Link the link containing the reference link) Returns the position in the source for the reference in a link.
private int	Returns: the start of this node, from the start of the first span getStartPos(Node the node node) Returns the start of this node, from the start of the first span.
public List<DCTree>	Returns: the trees that were built after using the visitor getTrees() Returns the trees that were built after using the visitor.
private int	Returns: the position in the original comment for a position in `source`, using `replaceAdjustPos` sourcePosToTreePos(int the position in `source` pos) Returns the position in the original comment for a position in `source`, using `replaceAdjustPos`.
private int	Returns: the position in the `source` string for a given `(line, column` toSourcePos(int the line index lineIndex, int the column index columnIndex) Returns the position in the `source` string for a given `(line, column`.
public void	visit(Link the link node link) Overrides jdk.internal.org.commonmark.node.AbstractVisitor.visit. Implements jdk.internal.org.commonmark.node.Visitor.visit. Visits a CommonMark `Link` node.
protected void	visitChildren(Node the node whose children should be visited node) Overrides jdk.internal.org.commonmark.node.AbstractVisitor.visitChildren. Processes a node and any children.

Inherited from jdk.internal.org.commonmark.node.AbstractVisitor:: visit visit visit visit visit visit visit visit visit visit visit visit visit visit visit visit visit visit visit visit visit visit

Field Detail

autorefScheme	back to summary
private final String autorefScheme

copyStartPos	back to summary
private int copyStartPos The start of source text to be copied literally when required.

document	back to summary
private final Node document The Markdown document being processed.

lineBreak back to summary

private static final Pattern lineBreak

The pattern for a line break. This is equivalent to the detection in the Markdown parser, so that (line, column) coordinates can be accurately converted back into source positions.

See Also: jdk.internal.org.commonmark.internal.DocumentParser#parse(String), jdk.internal.org.commonmark.internal.util.Parsing#findLineBreak(CharSequence, int)

m	back to summary
private final DocTreeMaker m

mainStartPos	back to summary
private int mainStartPos The initial position in the enclosing comment of the source being transformed.

NOSPAN	back to summary
private static final int[] NOSPAN

replaceAdjustPos	back to summary
private int replaceAdjustPos The current adjustment from positions in `source` to positions in the original comment, as used in doc tree nodes. The difference arises because of the use of U+FFFC characters for embedded objects. As the document (and source) are scanned, this offset is updated when U+FFFC characters are encountered.

replaceIter back to summary

private final Iterator<?> replaceIter

An iterator containing the values to be substituted into the generated tree when U+FFFC characters are encountered in the document. There is a 1-1 correspondence between the values returned by the iterator and the U+FFFC characters in the document. The replacement objects may be either DCTree objects or U+FFFC characters that were found in the original document.

source back to summary

private final String source

The source for the Markdown document being processed. The document has "source spans" that indirectly point into this string using (line, column) coordinates.

See Also: toSourcePos(int, int)

sourceLineOffsets	back to summary
private final int[] sourceLineOffsets An array giving the position of the first character after each newline in the source. Used to convert `(line, column)` coordinates to a character offset in `source`.

text	back to summary
private final StringBuilder text The source text being accumulated, prior to being placed in a Markdown source node (`RawTextTree` with kind `MARKDOWN`).

trees	back to summary
private List<DCTree> trees The list of trees being built. It may be temporarily replaced while visiting the children of `Link` codes.

Constructor Detail

Lower back to summary

public Lower(DocTreeMaker docTreeMaker, Node document, String source, int sourcePos, List<?> replacements, String autorefScheme)

Creates an instance of the visitor, given a document, the source text for the document and objects to be substituted when U+FFFC characters are encountered. Note the document does not itself contain any source text: it just contains SourceSpan objects that point into the source text using line and column indices.

Parameters

document:Node: the document to be converted
source:String: the source of the document to be converted
sourcePos:int: the position in the enclosing comment of the source to be converted
replacements:List<?>: the objects to be substituted when U+FFFC is encountered
autorefScheme:String: the scheme used for auto-generated references

Method Detail

copyTo back to summary

private void copyTo(int endPos)

Copies source text from the saved copy-start position to the given end position using the saved source, to the list of trees.

Parameters

endPos:int: the end position

flushText	back to summary
private void flushText(int pos) Flushes any text in the `text` buffer, by creating a new Markdown source text node and adding it to the list of trees.

getEndPos

back to summary

private int getEndPos(Node node)

Returns the end of this node, from the end of the last span. The end points to the first character not included in the span.

Parameters

node:Node: the node

Returns:int

the end of this node, from the end of the last span

getRefSpan back to summary

private int[] getRefSpan(String ref, Link link)

Returns the position in the source for the reference in a link. Many syntactic forms may yield a Link object, so scan the source looking for a match. Since the reference typically comes after any text (when they are different), scan the source backwards.

Parameters

ref:String: the reference to find
link:Link: the link containing the reference

Returns:int[]

the position in the source for the reference in a link

getStartPos

back to summary

private int getStartPos(Node node)

Returns the start of this node, from the start of the first span.

Parameters

node:Node: the node

Returns:int

the start of this node, from the start of the first span

getTrees

back to summary

public List<DCTree> getTrees()

Returns the trees that were built after using the visitor.

Returns:List<DCTree>: the trees that were built after using the visitor

sourcePosToTreePos back to summary

private int sourcePosToTreePos(int pos)

Returns the position in the original comment for a position in source, using replaceAdjustPos.

Parameters

pos:int: the position in source

Returns:int

the position in the original comment for a position in source, using replaceAdjustPos

toSourcePos back to summary

private int toSourcePos(int lineIndex, int columnIndex)

Returns the position in the source string for a given (line, column.

Parameters

lineIndex:int: the line index
columnIndex:int: the column index

Returns:int

the position in the source string for a given (line, column

visit back to summary

public void visit(Link link)

Overrides jdk.internal.org.commonmark.node.AbstractVisitor.visit.

Implements jdk.internal.org.commonmark.node.Visitor.visit.

Visits a CommonMark Link node. If the destination for the link begins with the autorefScheme convert it to {@link ...} or {@linkplain ...} DocTree node. {@link ...} will be used if the content (label) for the link is the same as the reference found after the code:; otherwise, {@linkplain ...} will be used. The label will be left blank for {@link ...} nodes, implying that a default label should be used, based on the program element that was referenced.

Parameters

link:Link: the link node

Annotations

@Override

visitChildren back to summary

protected void visitChildren(Node node)

Overrides jdk.internal.org.commonmark.node.AbstractVisitor.visitChildren.

Processes a node and any children. If the node has children, the children are each visited by calling their accept method, and then finally, if this is the top-level document node, any pending text is flushed. If the node does not have children, the source spans for the node are processed instead. Note that unlike the default implementation of visitChildren, the next child is not accessed until after the current child has been visited. This allows a child to peek at and possibly remove any child nodes that may follow it.

Parameters

node:Node: the node whose children should be visited

Annotations

@Override

public Class MarkdownTransformer

Nested and Inner Type Summary

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

private Class MarkdownTransformer.AutoRefInlineParserFactory

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

private Class MarkdownTransformer.DCTransformer

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

private Class MarkdownTransformer.Lower

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail