Skip to content

Commit

Permalink
8309566: Migrate away from TagletWriter and TagletWriterImpl
Browse files Browse the repository at this point in the history
8311974: Clean up Utils.getBlockTags

Reviewed-by: prappo
  • Loading branch information
jonathan-gibbons committed Jul 13, 2023
1 parent fb90af8 commit e51472e
Show file tree
Hide file tree
Showing 57 changed files with 2,428 additions and 2,626 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,6 @@
import jdk.javadoc.internal.doclets.toolkit.MemberSummaryWriter;
import jdk.javadoc.internal.doclets.toolkit.MemberWriter;
import jdk.javadoc.internal.doclets.toolkit.Resources;
import jdk.javadoc.internal.doclets.toolkit.taglets.DeprecatedTaglet;
import jdk.javadoc.internal.doclets.toolkit.util.Utils;

/**
Expand Down Expand Up @@ -257,8 +256,8 @@ private void addModifiers(Element member, Content target) {
* @param target the content to which the deprecated information will be added.
*/
protected void addDeprecatedInfo(Element member, Content target) {
Content output = (new DeprecatedTaglet()).getAllBlockTagOutput(member,
writer.getTagletWriterInstance(false));
var t = configuration.tagletManager.getTaglet(DocTree.Kind.DEPRECATED);
Content output = t.getAllBlockTagOutput(member, writer.getTagletWriterInstance(false));
if (!output.isEmpty()) {
target.add(HtmlTree.DIV(HtmlStyle.deprecationBlock, output));
}
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,7 @@
import java.util.Set;
import java.util.SortedSet;
import java.util.TreeSet;

import javax.lang.model.element.AnnotationMirror;
import javax.lang.model.element.Element;
import javax.lang.model.element.ModuleElement;
Expand All @@ -41,6 +42,7 @@

import com.sun.source.doctree.DeprecatedTree;
import com.sun.source.doctree.DocTree;

import jdk.javadoc.internal.doclets.formats.html.Navigation.PageMode;
import jdk.javadoc.internal.doclets.formats.html.markup.ContentBuilder;
import jdk.javadoc.internal.doclets.formats.html.markup.Entity;
Expand All @@ -51,7 +53,6 @@
import jdk.javadoc.internal.doclets.formats.html.markup.Text;
import jdk.javadoc.internal.doclets.toolkit.ClassWriter;
import jdk.javadoc.internal.doclets.toolkit.Content;
import jdk.javadoc.internal.doclets.toolkit.taglets.ParamTaglet;
import jdk.javadoc.internal.doclets.toolkit.util.ClassTree;
import jdk.javadoc.internal.doclets.toolkit.util.CommentHelper;
import jdk.javadoc.internal.doclets.toolkit.util.DocFileIOException;
Expand Down Expand Up @@ -92,6 +93,11 @@ public ClassWriterImpl(HtmlConfiguration configuration, TypeElement typeElement,
this.classTree = classTree;
}

@Override
public Content getOutputInstance() {
return new ContentBuilder();
}

@Override
public Content getHeader(String header) {
HtmlTree body = getBody(getWindowTitle(utils.getSimpleName(typeElement)));
Expand Down Expand Up @@ -173,7 +179,7 @@ public Content getClassInfo(Content classInfo) {
}

@Override
protected TypeElement getCurrentPageElement() {
public TypeElement getCurrentPageElement() {
return typeElement;
}

Expand Down Expand Up @@ -268,8 +274,8 @@ public void addClassTree(Content target) {
@Override
public void addParamInfo(Content target) {
if (utils.hasBlockTag(typeElement, DocTree.Kind.PARAM)) {
Content paramInfo = (new ParamTaglet()).getAllBlockTagOutput(typeElement,
getTagletWriterInstance(false));
var t = configuration.tagletManager.getTaglet(DocTree.Kind.PARAM);
Content paramInfo = t.getAllBlockTagOutput(typeElement, getTagletWriterInstance(false));
if (!paramInfo.isEmpty()) {
target.add(HtmlTree.DL(HtmlStyle.notes, paramInfo));
}
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -25,8 +25,13 @@

package jdk.javadoc.internal.doclets.formats.html;

import java.io.File;
import java.io.IOException;
import java.nio.file.InvalidPathException;
import java.nio.file.Path;
import java.time.ZonedDateTime;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.EnumSet;
import java.util.HashMap;
import java.util.List;
Expand All @@ -39,6 +44,7 @@
import javax.lang.model.element.Element;
import javax.lang.model.element.PackageElement;
import javax.lang.model.element.TypeElement;
import javax.tools.DocumentationTool;
import javax.tools.JavaFileManager;
import javax.tools.JavaFileObject;
import javax.tools.StandardJavaFileManager;
Expand All @@ -49,6 +55,7 @@
import jdk.javadoc.doclet.StandardDoclet;
import jdk.javadoc.doclet.Taglet;
import jdk.javadoc.internal.Versions;
import jdk.javadoc.internal.doclets.formats.html.taglets.TagletManager;
import jdk.javadoc.internal.doclets.toolkit.BaseConfiguration;
import jdk.javadoc.internal.doclets.toolkit.BaseOptions;
import jdk.javadoc.internal.doclets.toolkit.DocletException;
Expand All @@ -61,6 +68,7 @@
import jdk.javadoc.internal.doclets.toolkit.util.DocPaths;
import jdk.javadoc.internal.doclets.toolkit.util.NewAPIBuilder;
import jdk.javadoc.internal.doclets.toolkit.util.PreviewAPIListBuilder;
import jdk.javadoc.internal.doclets.toolkit.util.SimpleDocletException;

/**
* Configure the output based on the command-line options.
Expand Down Expand Up @@ -104,7 +112,7 @@ public class HtmlConfiguration extends BaseConfiguration {
* 2. items for elements are added in bulk before generating the index files
* 3. additional items are added as needed
*/
protected HtmlIndexBuilder mainIndex;
public HtmlIndexBuilder mainIndex;

/**
* The collection of deprecated items, if any, to be displayed on the deprecated-list page,
Expand Down Expand Up @@ -133,7 +141,7 @@ public class HtmlConfiguration extends BaseConfiguration {

public Contents contents;

protected final Messages messages;
public final Messages messages;

public DocPaths docPaths;

Expand All @@ -143,6 +151,11 @@ public class HtmlConfiguration extends BaseConfiguration {

private final HtmlOptions options;

/**
* The taglet manager.
*/
public TagletManager tagletManager;

/**
* Kinds of conditional pages.
*/
Expand Down Expand Up @@ -424,6 +437,125 @@ protected boolean finishOptionSettings0() throws DocletException {
return false;
}
}

String snippetPath = options.snippetPath();
if (snippetPath != null) {
Messages messages = getMessages();
JavaFileManager fm = getFileManager();
if (fm instanceof StandardJavaFileManager) {
try {
List<Path> sp = Arrays.stream(snippetPath.split(File.pathSeparator))
.map(Path::of)
.toList();
StandardJavaFileManager sfm = (StandardJavaFileManager) fm;
sfm.setLocationFromPaths(DocumentationTool.Location.SNIPPET_PATH, sp);
} catch (IOException | InvalidPathException e) {
throw new SimpleDocletException(messages.getResources().getText(
"doclet.error_setting_snippet_path", snippetPath, e), e);
}
} else {
throw new SimpleDocletException(messages.getResources().getText(
"doclet.cannot_use_snippet_path", snippetPath));
}
}

initTagletManager(options.customTagStrs());

return super.finishOptionSettings0();
}

/**
* Initialize the taglet manager. The strings to initialize the simple custom tags should
* be in the following format: "[tag name]:[location str]:[heading]".
*
* @param customTagStrs the set two-dimensional arrays of strings. These arrays contain
* either -tag or -taglet arguments.
*/
private void initTagletManager(Set<List<String>> customTagStrs) {
tagletManager = tagletManager != null ? tagletManager : new TagletManager(this);
JavaFileManager fileManager = getFileManager();
Messages messages = getMessages();
try {
tagletManager.initTagletPath(fileManager);
tagletManager.loadTaglets(fileManager);

for (List<String> args : customTagStrs) {
if (args.get(0).equals("-taglet")) {
tagletManager.addCustomTag(args.get(1), fileManager);
continue;
}
/* Since there are few constraints on the characters in a tag name,
* and real world examples with ':' in the tag name, we cannot simply use
* String.split(regex); instead, we tokenize the string, allowing
* special characters to be escaped with '\'. */
List<String> tokens = tokenize(args.get(1), 3);
switch (tokens.size()) {
case 1 -> {
String tagName = args.get(1);
if (tagletManager.isKnownCustomTag(tagName)) {
//reorder a standard tag
tagletManager.addNewSimpleCustomTag(tagName, null, "");
} else {
//Create a simple tag with the heading that has the same name as the tag.
StringBuilder heading = new StringBuilder(tagName + ":");
heading.setCharAt(0, Character.toUpperCase(tagName.charAt(0)));
tagletManager.addNewSimpleCustomTag(tagName, heading.toString(), "a");
}
}

case 2 ->
//Add simple taglet without heading, probably to excluding it in the output.
tagletManager.addNewSimpleCustomTag(tokens.get(0), tokens.get(1), "");

case 3 ->
tagletManager.addNewSimpleCustomTag(tokens.get(0), tokens.get(2), tokens.get(1));

default ->
messages.error("doclet.Error_invalid_custom_tag_argument", args.get(1));
}
}
} catch (IOException e) {
messages.error("doclet.taglet_could_not_set_location", e.toString());
}
}

/**
* Given a string, return an array of tokens, separated by ':'.
* The separator character can be escaped with the '\' character.
* The '\' character may also be escaped with the '\' character.
*
* @param s the string to tokenize
* @param maxTokens the maximum number of tokens returned. If the
* max is reached, the remaining part of s is appended
* to the end of the last token.
* @return an array of tokens
*/
private List<String> tokenize(String s, int maxTokens) {
List<String> tokens = new ArrayList<>();
StringBuilder token = new StringBuilder();
boolean prevIsEscapeChar = false;
for (int i = 0; i < s.length(); i += Character.charCount(i)) {
int currentChar = s.codePointAt(i);
if (prevIsEscapeChar) {
// Case 1: escaped character
token.appendCodePoint(currentChar);
prevIsEscapeChar = false;
} else if (currentChar == ':' && tokens.size() < maxTokens - 1) {
// Case 2: separator
tokens.add(token.toString());
token = new StringBuilder();
} else if (currentChar == '\\') {
// Case 3: escape character
prevIsEscapeChar = true;
} else {
// Case 4: regular character
token.appendCodePoint(currentChar);
}
}
if (token.length() > 0) {
tokens.add(token.toString());
}
return tokens;
}

}
Original file line number Diff line number Diff line change
Expand Up @@ -319,6 +319,16 @@ protected void generateOtherFiles(ClassTree classTree)
copyLegalFiles(options.createIndex());
}

@Override
protected void generateFiles() throws DocletException {
super.generateFiles();

if (configuration.tagletManager != null) { // may be null, if no files generated, perhaps because of errros
configuration.tagletManager.printReport();
}

}

private void copyJqueryFiles() throws DocletException {
List<String> files = Arrays.asList(
DocPaths.JQUERY_JS.getPath(),
Expand Down

1 comment on commit e51472e

@openjdk-notifier
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please sign in to comment.