From 0a1d593a04f3976d8116cfffc5c9c9a53054efb1 Mon Sep 17 00:00:00 2001 From: Martin Wittlinger Date: Wed, 10 Jan 2024 16:49:53 +0100 Subject: [PATCH] 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. --- doc/_data/sidebar_doc.yml | 7 +++++++ doc/spoon_javadoc.md | 14 +++++++------- .../java/spoon/javadoc/internal/Javadoc.java | 17 ++++++++++------- .../spoon/javadoc/internal/JavadocBlockTag.java | 2 ++ .../javadoc/internal/JavadocDescription.java | 2 ++ .../internal/JavadocDescriptionElement.java | 2 ++ .../javadoc/internal/JavadocInlineTag.java | 2 ++ .../spoon/javadoc/internal/JavadocSnippet.java | 2 ++ 8 files changed, 34 insertions(+), 14 deletions(-) diff --git a/doc/_data/sidebar_doc.yml b/doc/_data/sidebar_doc.yml index c8eba2008b8..6a6ddb31276 100644 --- 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 index a7274d74684..ced0f2de9b5 100644 --- 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 + + fr.inria.gforge.spoon + spoon-javadoc + $CurrentVersion + ``` ### Basic usage diff --git a/src/main/java/spoon/javadoc/internal/Javadoc.java b/src/main/java/spoon/javadoc/internal/Javadoc.java index dac54a782c3..1eb6c1d3b54 100644 --- 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. -* -*

It is composed by a description and a list of block tags. -* -*

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 @see AnotherClass) -*/ + * The structured content of a single Javadoc comment. + * + *

It is composed by a description and a list of block tags. + * + *

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 @see AnotherClass) + * + * @deprecated Use the new javadoc parser submodule, See Javadoc Parser. + */ +@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 index e784fc8b60b..afa22fb22cc 100644 --- a/src/main/java/spoon/javadoc/internal/JavadocBlockTag.java +++ b/src/main/java/spoon/javadoc/internal/JavadocBlockTag.java @@ -25,7 +25,9 @@ * *

Examples: @see AnotherClass @since v0.0.1 @author Jim O'Java * +* @deprecated Use the new javadoc parser submodule, See Javadoc Parser. */ +@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 index fbddf795587..36896ef1728 100644 --- 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 Javadoc Parser. */ + @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 index 743a1d96daa..c65b50f8a97 100644 --- a/src/main/java/spoon/javadoc/internal/JavadocDescriptionElement.java +++ b/src/main/java/spoon/javadoc/internal/JavadocDescriptionElement.java @@ -19,7 +19,9 @@ * *

So for example a text or {@link String} could be valid description * elements. +* @deprecated Use the new javadoc parser submodule, See Javadoc Parser. */ +@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 index e11dde27623..f7c84b9c023 100644 --- 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. * *

For example {@link String} +* @deprecated Use the new javadoc parser submodule, See Javadoc Parser. */ +@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 index f82fd374671..99e3ebe18c0 100644 --- a/src/main/java/spoon/javadoc/internal/JavadocSnippet.java +++ b/src/main/java/spoon/javadoc/internal/JavadocSnippet.java @@ -21,7 +21,9 @@ * *

For example in A class totally unrelated to {@link String}, I swear! we would * have two snippets: one before and one after the inline tag ({@link String}). +* @deprecated Use the new javadoc parser submodule, See Javadoc Parser. */ +@Deprecated(forRemoval = true, since = "11.0.0") public class JavadocSnippet implements JavadocDescriptionElement, Serializable { private static final long serialVersionUID = 1L; private String text;