diff options
Diffstat (limited to 'javaparser-core/src/main/java/com/github/javaparser/javadoc')
6 files changed, 669 insertions, 0 deletions
diff --git a/javaparser-core/src/main/java/com/github/javaparser/javadoc/Javadoc.java b/javaparser-core/src/main/java/com/github/javaparser/javadoc/Javadoc.java new file mode 100644 index 000000000..ba606c2f3 --- /dev/null +++ b/javaparser-core/src/main/java/com/github/javaparser/javadoc/Javadoc.java @@ -0,0 +1,167 @@ +/* + * Copyright (C) 2007-2010 Júlio Vilmar Gesser. + * Copyright (C) 2011, 2013-2016 The JavaParser Team. + * + * This file is part of JavaParser. + * + * JavaParser can be used either under the terms of + * a) the GNU Lesser General Public License as published by + * the Free Software Foundation, either version 3 of the License, or + * (at your option) any later version. + * b) the terms of the Apache License + * + * You should have received a copy of both licenses in LICENCE.LGPL and + * LICENCE.APACHE. Please refer to those files for details. + * + * JavaParser is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU Lesser General Public License for more details. + */ + +package com.github.javaparser.javadoc; + +import com.github.javaparser.ast.comments.JavadocComment; +import com.github.javaparser.javadoc.description.JavadocDescription; + +import java.util.LinkedList; +import java.util.List; + +import static com.github.javaparser.utils.Utils.*; + +/** + * The structured content of a single Javadoc comment. + * <p> + * It is composed by a description and a list of block tags. + * <p> + * An example would be the text contained in this very Javadoc comment. At the moment + * of this writing this comment does not contain any block tags (such as <code>@see AnotherClass</code>) + */ +public class Javadoc { + + private JavadocDescription description; + private List<JavadocBlockTag> blockTags; + + public Javadoc(JavadocDescription description) { + this.description = description; + this.blockTags = new LinkedList<>(); + } + + public Javadoc addBlockTag(JavadocBlockTag blockTag) { + this.blockTags.add(blockTag); + return this; + } + + /** + * For tags like "@return good things" where + * tagName is "return", + * and the rest is content. + */ + public Javadoc addBlockTag(String tagName, String content) { + return addBlockTag(new JavadocBlockTag(tagName, content)); + } + + /** + * For tags like "@param abc this is a parameter" where + * tagName is "param", + * parameter is "abc" + * and the rest is content. + */ + public Javadoc addBlockTag(String tagName, String parameter, String content) { + return addBlockTag(tagName, parameter + " " + content); + } + + public Javadoc addBlockTag(String tagName) { + return addBlockTag(tagName, ""); + } + + /** + * Return the text content of the document. It does not containing trailing spaces and asterisks + * at the start of the line. + */ + public String toText() { + StringBuilder sb = new StringBuilder(); + if (!description.isEmpty()) { + sb.append(description.toText()); + sb.append(EOL); + } + if (!blockTags.isEmpty()) { + sb.append(EOL); + } + blockTags.forEach(bt -> { + sb.append(bt.toText()); + sb.append(EOL); + }); + return sb.toString(); + } + + /** + * Create a JavadocComment, by formatting the text of the Javadoc using no indentation (expecting the pretty printer to do the formatting.) + */ + public JavadocComment toComment() { + return toComment(""); + } + + /** + * Create a JavadocComment, by formatting the text of the Javadoc using the given indentation. + */ + public JavadocComment toComment(String indentation) { + for (char c : indentation.toCharArray()) { + if (!Character.isWhitespace(c)) { + throw new IllegalArgumentException("The indentation string should be composed only by whitespace characters"); + } + } + StringBuilder sb = new StringBuilder(); + sb.append(EOL); + final String text = toText(); + if (!text.isEmpty()) { + for (String line : text.split(EOL)) { + sb.append(indentation); + sb.append(" * "); + sb.append(line); + sb.append(EOL); + } + } + sb.append(indentation); + sb.append(" "); + return new JavadocComment(sb.toString()); + } + + public JavadocDescription getDescription() { + return description; + } + + /** + * @return the current List of associated JavadocBlockTags + */ + public List<JavadocBlockTag> getBlockTags() { + return this.blockTags; + } + + @Override + public boolean equals(Object o) { + if (this == o) return true; + if (o == null || getClass() != o.getClass()) return false; + + Javadoc document = (Javadoc) o; + + return description.equals(document.description) && blockTags.equals(document.blockTags); + + } + + @Override + public int hashCode() { + int result = description.hashCode(); + result = 31 * result + blockTags.hashCode(); + return result; + } + + @Override + public String toString() { + return "Javadoc{" + + "description=" + description + + ", blockTags=" + blockTags + + '}'; + } + +} diff --git a/javaparser-core/src/main/java/com/github/javaparser/javadoc/JavadocBlockTag.java b/javaparser-core/src/main/java/com/github/javaparser/javadoc/JavadocBlockTag.java new file mode 100644 index 000000000..f33993170 --- /dev/null +++ b/javaparser-core/src/main/java/com/github/javaparser/javadoc/JavadocBlockTag.java @@ -0,0 +1,163 @@ +/* + * Copyright (C) 2007-2010 Júlio Vilmar Gesser. + * Copyright (C) 2011, 2013-2016 The JavaParser Team. + * + * This file is part of JavaParser. + * + * JavaParser can be used either under the terms of + * a) the GNU Lesser General Public License as published by + * the Free Software Foundation, either version 3 of the License, or + * (at your option) any later version. + * b) the terms of the Apache License + * + * You should have received a copy of both licenses in LICENCE.LGPL and + * LICENCE.APACHE. Please refer to those files for details. + * + * JavaParser is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU Lesser General Public License for more details. + */ + +package com.github.javaparser.javadoc; + +import com.github.javaparser.javadoc.description.JavadocDescription; + +import java.util.Optional; + +import static com.github.javaparser.utils.Utils.nextWord; +import static com.github.javaparser.utils.Utils.screamingToCamelCase; + +/** + * A block tag. + * <p> + * Typically they are found at the end of Javadoc comments. + * <p> + * Examples: + * <code>@see AnotherClass</code> + * <code>@since v0.0.1</code> + * <code>@author Jim O'Java</code> + */ +public class JavadocBlockTag { + + /** + * The type of tag: it could either correspond to a known tag (param, return, etc.) or represent + * an unknown tag. + */ + public enum Type { + AUTHOR, + DEPRECATED, + EXCEPTION, + PARAM, + RETURN, + SEE, + SERIAL, + SERIAL_DATA, + SERIAL_FIELD, + SINCE, + THROWS, + VERSION, + UNKNOWN; + + Type() { + this.keyword = screamingToCamelCase(name()); + } + + private String keyword; + + boolean hasName() { + return this == PARAM; + } + + static Type fromName(String tagName) { + for (Type t : Type.values()) { + if (t.keyword.equals(tagName)) { + return t; + } + } + return UNKNOWN; + } + + } + + private Type type; + private JavadocDescription content; + private Optional<String> name = Optional.empty(); + private String tagName; + + public JavadocBlockTag(Type type, String content) { + this.type = type; + this.tagName = type.keyword; + if (type.hasName()) { + this.name = Optional.of(nextWord(content)); + content = content.substring(this.name.get().length()).trim(); + } + this.content = JavadocDescription.parseText(content); + } + + public JavadocBlockTag(String tagName, String content) { + this(Type.fromName(tagName), content); + this.tagName = tagName; + } + + public static JavadocBlockTag createParamBlockTag(String paramName, String content) { + return new JavadocBlockTag(Type.PARAM, paramName + " " + content); + } + + public Type getType() { + return type; + } + + public JavadocDescription getContent() { + return content; + } + + public Optional<String> getName() { + return name; + } + + public String getTagName() { + return tagName; + } + + public String toText() { + StringBuilder sb = new StringBuilder(); + sb.append("@"); + sb.append(tagName); + name.ifPresent(s -> sb.append(" ").append(s)); + if (!content.isEmpty()) { + sb.append(" "); + sb.append(content.toText()); + } + return sb.toString(); + } + + @Override + public boolean equals(Object o) { + if (this == o) return true; + if (o == null || getClass() != o.getClass()) return false; + + JavadocBlockTag that = (JavadocBlockTag) o; + + if (type != that.type) return false; + if (!content.equals(that.content)) return false; + return name.equals(that.name); + } + + @Override + public int hashCode() { + int result = type.hashCode(); + result = 31 * result + content.hashCode(); + result = 31 * result + name.hashCode(); + return result; + } + + @Override + public String toString() { + return "JavadocBlockTag{" + + "type=" + type + + ", content='" + content + '\'' + + ", name=" + name + + '}'; + } +} diff --git a/javaparser-core/src/main/java/com/github/javaparser/javadoc/description/JavadocDescription.java b/javaparser-core/src/main/java/com/github/javaparser/javadoc/description/JavadocDescription.java new file mode 100644 index 000000000..82f818a98 --- /dev/null +++ b/javaparser-core/src/main/java/com/github/javaparser/javadoc/description/JavadocDescription.java @@ -0,0 +1,119 @@ +/* + * Copyright (C) 2007-2010 Júlio Vilmar Gesser. + * Copyright (C) 2011, 2013-2016 The JavaParser Team. + * + * This file is part of JavaParser. + * + * JavaParser can be used either under the terms of + * a) the GNU Lesser General Public License as published by + * the Free Software Foundation, either version 3 of the License, or + * (at your option) any later version. + * b) the terms of the Apache License + * + * You should have received a copy of both licenses in LICENCE.LGPL and + * LICENCE.APACHE. Please refer to those files for details. + * + * JavaParser is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU Lesser General Public License for more details. + */ + +package com.github.javaparser.javadoc.description; + +import com.github.javaparser.utils.Pair; + +import java.util.LinkedList; +import java.util.List; + +/** + * A javadoc text, potentially containing inline tags. + * + * For example <code>This class is totally unrelated to {@link com.github.javaparser.Range}</code> + */ +public class JavadocDescription { + + private List<JavadocDescriptionElement> elements; + + public static JavadocDescription parseText(String text) { + JavadocDescription instance = new JavadocDescription(); + int index = 0; + Pair<Integer, Integer> nextInlineTagPos; + while ((nextInlineTagPos = indexOfNextInlineTag(text, index)) != null) { + if (nextInlineTagPos.a != index) { + instance.addElement(new JavadocSnippet(text.substring(index, nextInlineTagPos.a + 1))); + } + instance.addElement(JavadocInlineTag.fromText(text.substring(nextInlineTagPos.a, nextInlineTagPos.b + 1))); + index = nextInlineTagPos.b; + } + if (index < text.length()) { + instance.addElement(new JavadocSnippet(text.substring(index))); + } + return instance; + } + + private static Pair<Integer, Integer> indexOfNextInlineTag(String text, int start) { + int index = text.indexOf("{@", start); + if (index == -1) { + return null; + } + // we are interested only in complete inline tags + int closeIndex = text.indexOf("}", index); + if (closeIndex == -1) { + return null; + } + return new Pair<>(index, closeIndex); + } + + public JavadocDescription() { + elements = new LinkedList<>(); + } + + public JavadocDescription(List<JavadocDescriptionElement> elements) { + this(); + + this.elements.addAll(elements); + } + + public boolean addElement(JavadocDescriptionElement element) { + return this.elements.add(element); + } + + public List<JavadocDescriptionElement> getElements() { + return this.elements; + } + + public String toText() { + StringBuilder sb = new StringBuilder(); + elements.forEach(e -> sb.append(e.toText())); + return sb.toString(); + } + + public boolean isEmpty() { + return toText().isEmpty(); + } + + @Override + public boolean equals(Object o) { + if (this == o) return true; + if (o == null || getClass() != o.getClass()) return false; + + JavadocDescription that = (JavadocDescription) o; + + return elements.equals(that.elements); + + } + + @Override + public int hashCode() { + return elements.hashCode(); + } + + @Override + public String toString() { + return "JavadocDescription{" + + "elements=" + elements + + '}'; + } + +} diff --git a/javaparser-core/src/main/java/com/github/javaparser/javadoc/description/JavadocDescriptionElement.java b/javaparser-core/src/main/java/com/github/javaparser/javadoc/description/JavadocDescriptionElement.java new file mode 100644 index 000000000..3d75b6c02 --- /dev/null +++ b/javaparser-core/src/main/java/com/github/javaparser/javadoc/description/JavadocDescriptionElement.java @@ -0,0 +1,31 @@ +/* + * Copyright (C) 2007-2010 Júlio Vilmar Gesser. + * Copyright (C) 2011, 2013-2016 The JavaParser Team. + * + * This file is part of JavaParser. + * + * JavaParser can be used either under the terms of + * a) the GNU Lesser General Public License as published by + * the Free Software Foundation, either version 3 of the License, or + * (at your option) any later version. + * b) the terms of the Apache License + * + * You should have received a copy of both licenses in LICENCE.LGPL and + * LICENCE.APACHE. Please refer to those files for details. + * + * JavaParser is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU Lesser General Public License for more details. + */ + +package com.github.javaparser.javadoc.description; + +/** + * An element of a description: either an inline tag or a piece of text. + * <p> + * So for example <code>a text</code> or <code>{@link String}</code> could be valid description elements. + */ +public interface JavadocDescriptionElement { + String toText(); +} diff --git a/javaparser-core/src/main/java/com/github/javaparser/javadoc/description/JavadocInlineTag.java b/javaparser-core/src/main/java/com/github/javaparser/javadoc/description/JavadocInlineTag.java new file mode 100644 index 000000000..8125bd510 --- /dev/null +++ b/javaparser-core/src/main/java/com/github/javaparser/javadoc/description/JavadocInlineTag.java @@ -0,0 +1,122 @@ +/* + * Copyright (C) 2007-2010 Júlio Vilmar Gesser. + * Copyright (C) 2011, 2013-2017 The JavaParser Team. + * + * This file is part of JavaParser. + * + * JavaParser can be used either under the terms of + * a) the GNU Lesser General Public License as published by + * the Free Software Foundation, either version 3 of the License, or + * (at your option) any later version. + * b) the terms of the Apache License + * + * You should have received a copy of both licenses in LICENCE.LGPL and + * LICENCE.APACHE. Please refer to those files for details. + * + * JavaParser is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU Lesser General Public License for more details. + */ + +package com.github.javaparser.javadoc.description; + +import static com.github.javaparser.utils.Utils.nextWord; +import static com.github.javaparser.utils.Utils.screamingToCamelCase; + +/** + * An inline tag contained in a Javadoc description. + * <p> + * For example <code>{@link String}</code> + */ +public class JavadocInlineTag implements JavadocDescriptionElement { + + public static JavadocDescriptionElement fromText(String text) { + if (!text.startsWith("{@")) { + throw new IllegalArgumentException(String.format("Expected to start with '{@'. Text '%s'", text)); + } + if (!text.endsWith("}")) { + throw new IllegalArgumentException(String.format("Expected to end with '}'. Text '%s'", text)); + } + text = text.substring(2, text.length() - 1); + String tagName = nextWord(text); + Type type = Type.fromName(tagName); + String content = text.substring(tagName.length()); + return new JavadocInlineTag(tagName, type, content); + } + + /** + * The type of tag: it could either correspond to a known tag (code, docRoot, etc.) or represent + * an unknown tag. + */ + public enum Type { + CODE, + DOC_ROOT, + INHERIT_DOC, + LINK, + LINKPLAIN, + LITERAL, + VALUE, + UNKNOWN; + + Type() { + this.keyword = screamingToCamelCase(name()); + } + + private String keyword; + + static JavadocInlineTag.Type fromName(String tagName) { + for (JavadocInlineTag.Type t : JavadocInlineTag.Type.values()) { + if (t.keyword.equals(tagName)) { + return t; + } + } + return UNKNOWN; + } + + } + + private String tagName; + private Type type; + private String content; + + public JavadocInlineTag(String tagName, Type type, String content) { + this.tagName = tagName; + this.type = type; + this.content = content; + } + + @Override + public String toText() { + return "@" + tagName + this.content; + } + + @Override + public boolean equals(Object o) { + if (this == o) return true; + if (o == null || getClass() != o.getClass()) return false; + + JavadocInlineTag that = (JavadocInlineTag) o; + + if (tagName != null ? !tagName.equals(that.tagName) : that.tagName != null) return false; + if (type != that.type) return false; + return content != null ? content.equals(that.content) : that.content == null; + } + + @Override + public int hashCode() { + int result = tagName != null ? tagName.hashCode() : 0; + result = 31 * result + (type != null ? type.hashCode() : 0); + result = 31 * result + (content != null ? content.hashCode() : 0); + return result; + } + + @Override + public String toString() { + return "JavadocInlineTag{" + + "tagName='" + tagName + '\'' + + ", type=" + type + + ", content='" + content + '\'' + + '}'; + } +} diff --git a/javaparser-core/src/main/java/com/github/javaparser/javadoc/description/JavadocSnippet.java b/javaparser-core/src/main/java/com/github/javaparser/javadoc/description/JavadocSnippet.java new file mode 100644 index 000000000..50b32cb31 --- /dev/null +++ b/javaparser-core/src/main/java/com/github/javaparser/javadoc/description/JavadocSnippet.java @@ -0,0 +1,67 @@ +/* + * Copyright (C) 2007-2010 Júlio Vilmar Gesser. + * Copyright (C) 2011, 2013-2016 The JavaParser Team. + * + * This file is part of JavaParser. + * + * JavaParser can be used either under the terms of + * a) the GNU Lesser General Public License as published by + * the Free Software Foundation, either version 3 of the License, or + * (at your option) any later version. + * b) the terms of the Apache License + * + * You should have received a copy of both licenses in LICENCE.LGPL and + * LICENCE.APACHE. Please refer to those files for details. + * + * JavaParser is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU Lesser General Public License for more details. + */ + +package com.github.javaparser.javadoc.description; + +/** + * A piece of text inside a Javadoc description. + * <p> + * For example in <code>A class totally unrelated to {@link String}, I swear!</code> we would have two snippets: one + * before and one after the inline tag (<code>{@link String}</code>). + */ +public class JavadocSnippet implements JavadocDescriptionElement { + private String text; + + public JavadocSnippet(String text) { + if (text == null) { + throw new NullPointerException(); + } + this.text = text; + } + + @Override + public String toText() { + return this.text; + } + + @Override + public boolean equals(Object o) { + if (this == o) return true; + if (o == null || getClass() != o.getClass()) return false; + + JavadocSnippet that = (JavadocSnippet) o; + + return text.equals(that.text); + + } + + @Override + public int hashCode() { + return text.hashCode(); + } + + @Override + public String toString() { + return "JavadocSnippet{" + + "text='" + text + '\'' + + '}'; + } +} |