issue433: define a JavadocDocument as a description and a list of blo…

…ck tags
javaparser · Jan 11, 2017 · 4c62581 · 4c62581
1 parent e25db1d
commit 4c62581
Show file tree

Hide file tree

Showing 9 changed files with 83 additions and 52 deletions.
diff --git a/javaparser-core/src/main/java/com/github/javaparser/ast/comments/JavadocComment.java b/javaparser-core/src/main/java/com/github/javaparser/ast/comments/JavadocComment.java
@@ -24,6 +24,7 @@
 import com.github.javaparser.Range;
 import com.github.javaparser.ast.visitor.GenericVisitor;
 import com.github.javaparser.ast.visitor.VoidVisitor;
+import com.github.javaparser.javadoc.JavadocDocument;
 
 /**
  * A Javadoc comment. <code>/&#42;&#42; a comment &#42;/</code>
@@ -53,4 +54,8 @@ public <R, A> R accept(GenericVisitor<R, A> v, A arg) {
     public <A> void accept(VoidVisitor<A> v, A arg) {
         v.visit(this, arg);
     }
+
+    public JavadocDocument parse() {
+        throw new UnsupportedOperationException();
+    }
 }
diff --git a/...github/javaparser/javadoc/JavadocTag.java → ...b/javaparser/javadoc/JavadocBlockTag.java b/...github/javaparser/javadoc/JavadocTag.java → ...b/javaparser/javadoc/JavadocBlockTag.java
@@ -21,6 +21,14 @@
 
 package com.github.javaparser.javadoc;
 
-public abstract class JavadocTag implements JavadocTextElement {
+public class JavadocBlockTag {
-    private String name;
+    public enum Type {
+        PARAM,
+        RETURN,
+        UNKNOWN
+    }
+
+    public JavadocBlockTag(Type type, String content) {
+
+    }
 }
diff --git a/javaparser-core/src/main/java/com/github/javaparser/javadoc/JavadocDocument.java b/javaparser-core/src/main/java/com/github/javaparser/javadoc/JavadocDocument.java
@@ -21,28 +21,32 @@
 
 package com.github.javaparser.javadoc;
 
-import java.util.Optional;
+import com.github.javaparser.ast.comments.JavadocComment;
+import com.github.javaparser.javadoc.description.JavadocDescription;
 
+import java.util.LinkedList;
+import java.util.List;
+
+/**
+ * The structured content of a single Javadoc Comment.
+ * <p>
+ * It is composed by a description and a list of block tags.
+ */
 public class JavadocDocument {
-    private JavadocText summary;
+    private JavadocDescription description;
-    private Optional<JavadocText> details;
+    private List<JavadocBlockTag> blockTags;
 
-    public JavadocDocument(JavadocText summary) {
+    public JavadocDocument(JavadocDescription description) {
-        this.summary = summary;
+        this.description = description;
-        this.details = Optional.empty();
+        this.blockTags = new LinkedList<>();
     }
 
-    public JavadocDocument(JavadocText summary, JavadocText details) {
+    public void addBlockTag(JavadocBlockTag blockTag) {
-        this.summary = summary;
+        this.blockTags.add(blockTag);
-        this.details = Optional.of(details);
     }
 
-    @Override
+    public JavadocComment toJavadocComment() {
-    public String toString() {
+        throw new UnsupportedOperationException();
-        return "JavadocDocument{" +
-                "summary=" + summary +
-                ", details=" + details +
-                '}';
     }
 
     @Override
@@ -52,15 +56,23 @@ public boolean equals(Object o) {
 
         JavadocDocument document = (JavadocDocument) o;
 
-        if (!summary.equals(document.summary)) return false;
+        if (!description.equals(document.description)) return false;
-        return details.equals(document.details);
+        return blockTags.equals(document.blockTags);
 
     }
 
     @Override
     public int hashCode() {
-        int result = summary.hashCode();
+        int result = description.hashCode();
-        result = 31 * result + details.hashCode();
+        result = 31 * result + blockTags.hashCode();
         return result;
     }
+
+    @Override
+    public String toString() {
+        return "JavadocDocument{" +
+                "description=" + description +
+                ", blockTags=" + blockTags +
+                '}';
+    }
 }
diff --git a/javaparser-core/src/main/java/com/github/javaparser/javadoc/JavadocParser.java b/javaparser-core/src/main/java/com/github/javaparser/javadoc/JavadocParser.java
@@ -22,21 +22,25 @@
 package com.github.javaparser.javadoc;
 
 import com.github.javaparser.ast.comments.JavadocComment;
+import com.github.javaparser.javadoc.description.JavadocDescription;
 
 import java.util.Arrays;
 import java.util.List;
 import java.util.stream.Collectors;
 
+/**
+ * The class responsible for parsing the content of JavadocComments and produce JavadocDocuments.
+ */
 public class JavadocParser {
 
     public JavadocDocument parse(JavadocComment comment) {
         return parse(comment.getContent());
     }
 
     public JavadocDocument parse(String commentContent) {
-        List<String> cleanLines = cleanLines(commentContent);
+        /*List<String> cleanLines = cleanLines(commentContent);
         if (cleanLines.isEmpty()) {
-            return new JavadocDocument(JavadocText.fromText(""));
+            return new JavadocDocument(JavadocDescription.fromText(""));
         } else if (cleanLines.size() == 1) {
             String summaryText = trimRight(cleanLines.get(0));
             return new JavadocDocument(parseText(summaryText));
@@ -46,19 +50,20 @@ public JavadocDocument parse(String commentContent) {
             if (detailsText.isEmpty()) {
                 return new JavadocDocument(parseText(summaryText));
             }
-            return new JavadocDocument(JavadocText.fromText(summaryText), JavadocText.fromText(detailsText));
+            return new JavadocDocument(JavadocDescription.fromText(summaryText), JavadocDescription.fromText(detailsText));
-        }
+        }*/
+        throw new UnsupportedOperationException();
     }
 
-    private String trimRight(String string) {
+    /*private String trimRight(String string) {
         while (string.endsWith(" ") || string.endsWith("\t")) {
             string = string.substring(0, string.length() - 1);
         }
         return string;
     }
 
-    private JavadocText parseText(String content) {
+    private JavadocDescription parseText(String content) {
-        return JavadocText.fromText(content);
+        return JavadocDescription.fromText(content);
     }
 
     private List<String> cleanLines(String content) {
@@ -108,5 +113,5 @@ static int startsWithAsterisk(String line) {
         } else {
             return -1;
         }
-    }
+    }*/
 }
diff --git a/...ithub/javaparser/javadoc/JavadocText.java → ...vadoc/description/JavadocDescription.java b/...ithub/javaparser/javadoc/JavadocText.java → ...vadoc/description/JavadocDescription.java
@@ -19,29 +19,29 @@
  * GNU Lesser General Public License for more details.
  */
 
-package com.github.javaparser.javadoc;
+package com.github.javaparser.javadoc.description;
 
 import java.util.LinkedList;
 import java.util.List;
 
 /**
- * A text, potentially containing tags.
+ * A text, potentially containing inline tags.
  */
-public class JavadocText {
+public class JavadocDescription {
 
-    private List<JavadocTextElement> elements;
+    private List<JavadocDescriptionElement> elements;
 
-    public static JavadocText fromText(String text) {
+    public static JavadocDescription fromText(String text) {
-        JavadocText instance = new JavadocText();
+        JavadocDescription instance = new JavadocDescription();
         instance.addElement(new JavadocSnippet(text));
         return instance;
     }
 
-    public JavadocText() {
+    public JavadocDescription() {
         elements = new LinkedList<>();
     }
 
-    public void addElement(JavadocTextElement element) {
+    public void addElement(JavadocDescriptionElement element) {
         this.elements.add(element);
     }
 
@@ -56,7 +56,7 @@ public boolean equals(Object o) {
         if (this == o) return true;
         if (o == null || getClass() != o.getClass()) return false;
 
-        JavadocText that = (JavadocText) o;
+        JavadocDescription that = (JavadocDescription) o;
 
         return elements.equals(that.elements);
 
@@ -69,7 +69,7 @@ public int hashCode() {
 
     @Override
     public String toString() {
-        return "JavadocText{" +
+        return "JavadocDescription{" +
                 "elements=" + elements +
                 '}';
     }

diff --git a/...avaparser/javadoc/JavadocTextElement.java → ...escription/JavadocDescriptionElement.java b/...avaparser/javadoc/JavadocTextElement.java → ...escription/JavadocDescriptionElement.java
@@ -19,8 +19,8 @@
  * GNU Lesser General Public License for more details.
  */
 
-package com.github.javaparser.javadoc;
+package com.github.javaparser.javadoc.description;
 
-public interface JavadocTextElement {
+public interface JavadocDescriptionElement {
     String toText();
 }
diff --git a/.../javaparser/javadoc/SimpleJavadocTag.java → ...javadoc/description/JavadocInlineTag.java b/.../javaparser/javadoc/SimpleJavadocTag.java → ...javadoc/description/JavadocInlineTag.java
@@ -19,9 +19,9 @@
  * GNU Lesser General Public License for more details.
  */
 
-package com.github.javaparser.javadoc;
+package com.github.javaparser.javadoc.description;
 
-public class SimpleJavadocTag extends JavadocTag {
+public class JavadocInlineTag implements JavadocDescriptionElement {
     @Override
     public String toText() {
         throw new UnsupportedOperationException();

diff --git a/...ub/javaparser/javadoc/JavadocSnippet.java → ...r/javadoc/description/JavadocSnippet.java b/...ub/javaparser/javadoc/JavadocSnippet.java → ...r/javadoc/description/JavadocSnippet.java
@@ -19,9 +19,9 @@
  * GNU Lesser General Public License for more details.
  */
 
-package com.github.javaparser.javadoc;
+package com.github.javaparser.javadoc.description;
 
-public class JavadocSnippet implements JavadocTextElement {
+public class JavadocSnippet implements JavadocDescriptionElement {
     private String text;
 
     public JavadocSnippet(String text) {

diff --git a/javaparser-testing/src/test/java/com/github/javaparser/javadoc/JavadocParserTest.java b/javaparser-testing/src/test/java/com/github/javaparser/javadoc/JavadocParserTest.java
@@ -21,6 +21,7 @@
 
 package com.github.javaparser.javadoc;
 
+import com.github.javaparser.javadoc.description.JavadocDescription;
 import org.junit.Test;
 
 import static org.junit.Assert.assertEquals;
@@ -29,19 +30,19 @@ public class JavadocParserTest {
 
     @Test
     public void parseSimplestContent() {
-        assertEquals(new JavadocDocument(JavadocText.fromText("A simple line of text")),
+        assertEquals(new JavadocDocument(JavadocDescription.fromText("A simple line of text")),
                 new JavadocParser().parse("A simple line of text"));
     }
 
     @Test
     public void parseSingleLineWithSpacing() {
-        assertEquals(new JavadocDocument(JavadocText.fromText("The line number of the first character of this Token.")),
+        assertEquals(new JavadocDocument(JavadocDescription.fromText("The line number of the first character of this Token.")),
                 new JavadocParser().parse(" The line number of the first character of this Token. "));
     }
 
     @Test
     public void parseSingleLineWithNewLines() {
-        assertEquals(new JavadocDocument(JavadocText.fromText("The string image of the token.")),
+        assertEquals(new JavadocDocument(JavadocDescription.fromText("The string image of the token.")),
                 new JavadocParser().parse("\n" +
                         "   * The string image of the token.\n" +
                         "   "));
@@ -54,8 +55,8 @@ public void parseCommentWithNewLines() {
                 "   * Increment only if the <i>serialized</i> form of the\n" +
                 "   * class changes.\n" +
                 "   ";
-        assertEquals(new JavadocDocument(JavadocText.fromText("The version identifier for this Serializable class."),
+        assertEquals(new JavadocDocument(JavadocDescription.fromText("The version identifier for this Serializable class."),
-                        JavadocText.fromText("Increment only if the <i>serialized</i> form of the\n" +
+                        JavadocDescription.fromText("Increment only if the <i>serialized</i> form of the\n" +
                                 "class changes.\n")),
                 new JavadocParser().parse(text));
     }
@@ -68,8 +69,8 @@ public void parseCommentWithIndentation() {
                 "   *    case MyParserConstants.ID : return new IDToken(ofKind, image);\n" +
                 "   *\n" +
                 "   * to the following switch statement. Then you can cast matchedToken";
-        assertEquals(new JavadocDocument(JavadocText.fromText("Returns a new Token object, by default."),
+        assertEquals(new JavadocDocument(JavadocDescription.fromText("Returns a new Token object, by default."),
-                        JavadocText.fromText("However, if you want, you can create and return subclass objects based on the value of ofKind.\n" +
+                        JavadocDescription.fromText("However, if you want, you can create and return subclass objects based on the value of ofKind.\n" +
                                 "\n" +
                                 "   case MyParserConstants.ID : return new IDToken(ofKind, image);\n" +
                                 "\n" +