doc: Add Javadoc Analysis to sidebar and deprecate old Javadoc classes

Added Javadoc Analysis section in the sidebar_doc.yml file. Deprecated several old classes related to the handling of Javadoc comments in favor of the new javadoc parser submodule. Updated the installation instructions in spoon_javadoc.md to reflect these changes.
INRIA · Jan 12, 2024 · 0a1d593 · 0a1d593
1 parent cf14fb1
commit 0a1d593
Show file tree

Hide file tree

Showing 8 changed files with 34 additions and 14 deletions.
diff --git a/doc/_data/sidebar_doc.yml b/doc/_data/sidebar_doc.yml
@@ -53,6 +53,13 @@ entries:
           product: all
           version: all
 
+        - title: Javadoc Analysis
+          url: /spoon_javadoc.html
+          audience: writers, designers
+          platform: all
+          product: all
+          version: all
+
         - title: FAQ
           url: /faq.html
           audience: writers, designers

diff --git a/doc/spoon_javadoc.md b/doc/spoon_javadoc.md
@@ -15,13 +15,13 @@ converting them into your own format.
 
 ### Installation
 
-On a Unix-like system, the following set of commands should be sufficient for
-getting spoon-javadoc up and running from scratch.
-
-```
-$ git clone https://github.com/INRIA/spoon.git
-$ cd spoon/spoon-pom
-$ mvn install
+To use spoon-javadoc, add the following dependency to your `pom.xml`:
+```xml
+<dependency>
+    <groupId>fr.inria.gforge.spoon</groupId>
+    <artifactId>spoon-javadoc</artifactId>
+    <version>$CurrentVersion</version>
+</dependency>
 ```
 
 ### Basic usage

diff --git a/src/main/java/spoon/javadoc/internal/Javadoc.java b/src/main/java/spoon/javadoc/internal/Javadoc.java
@@ -26,13 +26,16 @@
 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;
 

diff --git a/src/main/java/spoon/javadoc/internal/JavadocBlockTag.java b/src/main/java/spoon/javadoc/internal/JavadocBlockTag.java
@@ -25,7 +25,9 @@
 *
 * <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;
 

diff --git a/src/main/java/spoon/javadoc/internal/JavadocDescription.java b/src/main/java/spoon/javadoc/internal/JavadocDescription.java
@@ -20,7 +20,9 @@
 
 	/**
 	* 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;
 

diff --git a/src/main/java/spoon/javadoc/internal/JavadocDescriptionElement.java b/src/main/java/spoon/javadoc/internal/JavadocDescriptionElement.java
@@ -19,7 +19,9 @@
 *
 * <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();

diff --git a/src/main/java/spoon/javadoc/internal/JavadocInlineTag.java b/src/main/java/spoon/javadoc/internal/JavadocInlineTag.java
@@ -20,7 +20,9 @@
 * 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;
 

diff --git a/src/main/java/spoon/javadoc/internal/JavadocSnippet.java b/src/main/java/spoon/javadoc/internal/JavadocSnippet.java
@@ -21,7 +21,9 @@
 *
 * <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;