refactor: Deprecate old Javadoc classes

src/main/java/spoon/javadoc/internal/Javadoc.java

@@ -14,7 +14,7 @@
  */
 package spoon.javadoc.internal;
 
 import static spoon.javadoc.internal.JavadocInlineTag.nextWord;
 import java.io.Serializable;
 import java.util.Arrays;
 import java.util.Collections;
@@ -26,29 +26,32 @@
 import spoon.reflect.code.CtComment;
 
 /**
-* 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>)
-*/
+ * 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>)
+ *
+ * @deprecated Use the new javadoc parser submodule, see <a href="https://spoon.gforge.inria.fr/spoon_javadoc.html">Javadoc Parser</a>.
+ */
+@Deprecated(forRemoval = true, since = "11.0.0")
 public class Javadoc implements Serializable {
 	private static final long serialVersionUID = 1L;
 
 	private JavadocDescription description;
 	private List<JavadocBlockTag> blockTags;
 
 	public Javadoc() {
 		this(new JavadocDescription());
 	}
 
 	public Javadoc(JavadocDescription description) {
 		this.description = description;
 		this.blockTags = new LinkedList<>();
 	}
 
 	public Javadoc addBlockTag(JavadocBlockTag blockTag) {
 		this.blockTags.add(blockTag);
 		return this;
 	}
@@ -68,8 +71,8 @@
 		*/
 	public String toText() {
 		StringBuilder sb = new StringBuilder();
 		if (!description.isEmpty()) {
 			sb.append(description.toText());
 			sb.append(System.lineSeparator());
 		}
 		if (!blockTags.isEmpty()) {
@@ -77,18 +80,18 @@
 		}
 		blockTags.forEach(
 			bt -> {
 				sb.append(bt.toText());
 				sb.append(System.lineSeparator());
 			});
 		return sb.toString();
 	}
 
 	public JavadocDescription getDescription() {
 		return description;
 	}
 
 	/** @return the current List of associated JavadocBlockTags */
 	public List<JavadocBlockTag> getBlockTags() {
 		return this.blockTags;
 	}
 
@@ -103,12 +106,12 @@
 
 		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;
 	}
@@ -123,20 +126,20 @@
 			Pattern.compile("^\\s*" + BLOCK_TAG_PREFIX, Pattern.MULTILINE);
 
 	/** parse the description part (before tags) of a Javadoc */
 	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.getLeft() != index) {
 			instance.addElement(new JavadocSnippet(text.substring(index, nextInlineTagPos.getLeft())));
 			}
 			instance.addElement(
 				JavadocInlineTag.fromText(text.substring(nextInlineTagPos.getLeft(), nextInlineTagPos.getRight() + 1)));
 			index = nextInlineTagPos.getRight() + 1;
 		}
 		if (index < text.length()) {
 			instance.addElement(new JavadocSnippet(text.substring(index)));
 		}
 		return instance;
 	}
@@ -225,11 +228,11 @@
 		return document;
 	}
 
 	private static JavadocBlockTag parseBlockTag(String line) {
 		line = line.trim().substring(1);
 		String tagName = nextWord(line);
 		String rest = line.substring(tagName.length()).trim();
 		return new JavadocBlockTag(tagName, rest);
 	}
 
 	private static boolean isABlockLine(String line) {

src/main/java/spoon/javadoc/internal/JavadocBlockTag.java

@@ -25,12 +25,14 @@
 *
 * <p>Examples: <code>@see AnotherClass</code> <code>@since v0.0.1</code> <code>@author Jim O'Java
 * </code>
+* @deprecated Use the new javadoc parser submodule, see <a href="https://spoon.gforge.inria.fr/spoon_javadoc.html">Javadoc Parser</a>.
 */
+@Deprecated(forRemoval = true, since = "11.0.0")
 public class JavadocBlockTag implements Serializable {
 	private static final long serialVersionUID = 1L;
 
 	private CtJavaDocTag.TagType type;
 	private JavadocDescription content;
 	private String name = "";
 	private String tagName;
 	private String tagRealName;
@@ -38,14 +40,14 @@
 	public JavadocBlockTag(CtJavaDocTag.TagType type, String content) {
 		this.type = type;
 		this.tagName = type.getName();
 		this.content = Javadoc.parseText(content);
 	}
 
 	public JavadocBlockTag(CtJavaDocTag.TagType type, String tagRealName, String content) {
 		this.type = type;
 		this.tagName = type.getName();
 		this.tagRealName = tagRealName;
 		this.content = Javadoc.parseText(content);
 	}
 
 	public JavadocBlockTag(String tagName, String content) {
@@ -63,7 +65,7 @@
 		return type;
 	}
 
 	public JavadocDescription getContent() {
 		return content;
 	}
 
@@ -89,9 +91,9 @@
 		sb.append("@");
 		sb.append(tagRealName);
 		sb.append(" ").append(name);
 		if (!content.isEmpty()) {
 			sb.append(" ");
 			sb.append(content.toText());
 		}
 		return sb.toString();
 	}
@@ -110,7 +112,7 @@
 		if (type != that.type) {
 			return false;
 		}
 		if (!content.equals(that.content)) {
 			return false;
 		}
 		return name.equals(that.name);
@@ -119,7 +121,7 @@
 	@Override
 	public int hashCode() {
 		int result = type.hashCode();
 		result = 31 * result + content.hashCode();
 		result = 31 * result + name.hashCode();
 		return result;
 	}

src/main/java/spoon/javadoc/internal/JavadocDescription.java

@@ -20,33 +20,35 @@
 
 	/**
 	* A javadoc text, potentially containing inline tags.
+	* @deprecated Use the new javadoc parser submodule, see <a href="https://spoon.gforge.inria.fr/spoon_javadoc.html">Javadoc Parser</a>.
 	*/
+	@Deprecated(forRemoval = true, since = "11.0.0")
 	public class JavadocDescription implements Serializable {
 	private static final long serialVersionUID = 1L;
 
 	private List<JavadocDescriptionElement> elements;
 
 	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();
 	}
 

src/main/java/spoon/javadoc/internal/JavadocDescriptionElement.java

@@ -19,8 +19,10 @@
 *
 * <p>So for example <code>a text</code> or <code>{@link String}</code> could be valid description
 * elements.
+* @deprecated Use the new javadoc parser submodule, see <a href="https://spoon.gforge.inria.fr/spoon_javadoc.html">Javadoc Parser</a>.
 */
+@Deprecated(forRemoval = true, since = "11.0.0")
 public interface JavadocDescriptionElement {
 	/** pretty-prints the Javadoc fragment */
 	String toText();
 }

src/main/java/spoon/javadoc/internal/JavadocInlineTag.java

@@ -20,8 +20,10 @@
 * An inline tag contained in a Javadoc description.
 *
 * <p>For example <code>{@link String}</code>
+* @deprecated Use the new javadoc parser submodule, see <a href="https://spoon.gforge.inria.fr/spoon_javadoc.html">Javadoc Parser</a>.
 */
+@Deprecated(forRemoval = true, since = "11.0.0")
 public class JavadocInlineTag implements JavadocDescriptionElement, Serializable {
 	private static final long serialVersionUID = 1L;
 
 	/** Return the next word of the string, in other words it stops when a space is encountered. */
@@ -34,7 +36,7 @@
 	}
 
 	/** parses a Javadoc tag */
 	public static JavadocDescriptionElement fromText(String text) {
 		if (!text.startsWith("{@")) {
 			throw new IllegalArgumentException(
 				String.format("Expected to start with '{@'. Text '%s'", text));

src/main/java/spoon/javadoc/internal/JavadocSnippet.java

@@ -21,8 +21,10 @@
 *
 * <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>).
+* @deprecated Use the new javadoc parser submodule, see <a href="https://spoon.gforge.inria.fr/spoon_javadoc.html">Javadoc Parser</a>.
 */
+@Deprecated(forRemoval = true, since = "11.0.0")
 public class JavadocSnippet implements JavadocDescriptionElement, Serializable {
 	private static final long serialVersionUID = 1L;
 	private String text;