From 0a1d593a04f3976d8116cfffc5c9c9a53054efb1 Mon Sep 17 00:00:00 2001 From: Martin Wittlinger Date: Wed, 10 Jan 2024 16:49:53 +0100 Subject: [PATCH 1/4] 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; From 9bb77e39e7518756113e569c17c6a8a121b00203 Mon Sep 17 00:00:00 2001 From: Martin Wittlinger Date: Wed, 10 Jan 2024 20:21:04 +0100 Subject: [PATCH 2/4] Apply suggestions from code review Co-authored-by: I-Al-Istannen --- doc/spoon_javadoc.md | 2 +- src/main/java/spoon/javadoc/internal/JavadocBlockTag.java | 2 +- src/main/java/spoon/javadoc/internal/JavadocDescription.java | 2 +- .../java/spoon/javadoc/internal/JavadocDescriptionElement.java | 2 +- src/main/java/spoon/javadoc/internal/JavadocInlineTag.java | 2 +- src/main/java/spoon/javadoc/internal/JavadocSnippet.java | 2 +- 6 files changed, 6 insertions(+), 6 deletions(-) diff --git a/doc/spoon_javadoc.md b/doc/spoon_javadoc.md index ced0f2de9b5..73e1b6cf534 100644 --- a/doc/spoon_javadoc.md +++ b/doc/spoon_javadoc.md @@ -20,7 +20,7 @@ To use spoon-javadoc, add the following dependency to your `pom.xml`: fr.inria.gforge.spoon spoon-javadoc - $CurrentVersion + $currentVersion ``` diff --git a/src/main/java/spoon/javadoc/internal/JavadocBlockTag.java b/src/main/java/spoon/javadoc/internal/JavadocBlockTag.java index afa22fb22cc..9e42c22a901 100644 --- a/src/main/java/spoon/javadoc/internal/JavadocBlockTag.java +++ b/src/main/java/spoon/javadoc/internal/JavadocBlockTag.java @@ -25,7 +25,7 @@ * *

Examples: @see AnotherClass @since v0.0.1 @author Jim O'Java * -* @deprecated Use the new javadoc parser submodule, See Javadoc Parser. +* @deprecated Use the new javadoc parser submodule, see Javadoc Parser. */ @Deprecated(forRemoval = true, since = "11.0.0") public class JavadocBlockTag implements Serializable { diff --git a/src/main/java/spoon/javadoc/internal/JavadocDescription.java b/src/main/java/spoon/javadoc/internal/JavadocDescription.java index 36896ef1728..08e1313bea8 100644 --- a/src/main/java/spoon/javadoc/internal/JavadocDescription.java +++ b/src/main/java/spoon/javadoc/internal/JavadocDescription.java @@ -20,7 +20,7 @@ /** * A javadoc text, potentially containing inline tags. - * @deprecated Use the new javadoc parser submodule, See Javadoc Parser. + * @deprecated Use the new javadoc parser submodule, see Javadoc Parser. */ @Deprecated(forRemoval = true, since = "11.0.0") public class JavadocDescription implements Serializable { diff --git a/src/main/java/spoon/javadoc/internal/JavadocDescriptionElement.java b/src/main/java/spoon/javadoc/internal/JavadocDescriptionElement.java index c65b50f8a97..130b92a1d67 100644 --- a/src/main/java/spoon/javadoc/internal/JavadocDescriptionElement.java +++ b/src/main/java/spoon/javadoc/internal/JavadocDescriptionElement.java @@ -19,7 +19,7 @@ * *

So for example a text or {@link String} could be valid description * elements. -* @deprecated Use the new javadoc parser submodule, See Javadoc Parser. +* @deprecated Use the new javadoc parser submodule, see Javadoc Parser. */ @Deprecated(forRemoval = true, since = "11.0.0") public interface JavadocDescriptionElement { diff --git a/src/main/java/spoon/javadoc/internal/JavadocInlineTag.java b/src/main/java/spoon/javadoc/internal/JavadocInlineTag.java index f7c84b9c023..6e50a12b5e3 100644 --- a/src/main/java/spoon/javadoc/internal/JavadocInlineTag.java +++ b/src/main/java/spoon/javadoc/internal/JavadocInlineTag.java @@ -20,7 +20,7 @@ * An inline tag contained in a Javadoc description. * *

For example {@link String} -* @deprecated Use the new javadoc parser submodule, See Javadoc Parser. +* @deprecated Use the new javadoc parser submodule, see Javadoc Parser. */ @Deprecated(forRemoval = true, since = "11.0.0") public class JavadocInlineTag implements JavadocDescriptionElement, Serializable { diff --git a/src/main/java/spoon/javadoc/internal/JavadocSnippet.java b/src/main/java/spoon/javadoc/internal/JavadocSnippet.java index 99e3ebe18c0..5edd52d4587 100644 --- a/src/main/java/spoon/javadoc/internal/JavadocSnippet.java +++ b/src/main/java/spoon/javadoc/internal/JavadocSnippet.java @@ -21,7 +21,7 @@ * *

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 Use the new javadoc parser submodule, see Javadoc Parser. */ @Deprecated(forRemoval = true, since = "11.0.0") public class JavadocSnippet implements JavadocDescriptionElement, Serializable { From fbf273d678d072f38eb1a61d473d7cf383579437 Mon Sep 17 00:00:00 2001 From: Martin Wittlinger Date: Tue, 23 Jan 2024 17:02:07 +0100 Subject: [PATCH 3/4] up --- doc/_data/sidebar_doc.yml | 7 ------- doc/spoon_javadoc.md | 14 +++++++------- 2 files changed, 7 insertions(+), 14 deletions(-) diff --git a/doc/_data/sidebar_doc.yml b/doc/_data/sidebar_doc.yml index 6a6ddb31276..c8eba2008b8 100644 --- a/doc/_data/sidebar_doc.yml +++ b/doc/_data/sidebar_doc.yml @@ -53,13 +53,6 @@ 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 73e1b6cf534..a7274d74684 100644 --- a/doc/spoon_javadoc.md +++ b/doc/spoon_javadoc.md @@ -15,13 +15,13 @@ converting them into your own format. ### Installation -To use spoon-javadoc, add the following dependency to your `pom.xml`: -```xml - - fr.inria.gforge.spoon - spoon-javadoc - $currentVersion - +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 ``` ### Basic usage From c8efa8f52bffbcfd8c6b2a11775f5eb872e5ff2b Mon Sep 17 00:00:00 2001 From: Martin Wittlinger Date: Thu, 25 Jan 2024 20:44:21 +0100 Subject: [PATCH 4/4] Update src/main/java/spoon/javadoc/internal/Javadoc.java Co-authored-by: I-Al-Istannen --- src/main/java/spoon/javadoc/internal/Javadoc.java | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/main/java/spoon/javadoc/internal/Javadoc.java b/src/main/java/spoon/javadoc/internal/Javadoc.java index 1eb6c1d3b54..f8f7a7290aa 100644 --- a/src/main/java/spoon/javadoc/internal/Javadoc.java +++ b/src/main/java/spoon/javadoc/internal/Javadoc.java @@ -33,7 +33,7 @@ *

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 Use the new javadoc parser submodule, see Javadoc Parser. */ @Deprecated(forRemoval = true, since = "11.0.0") public class Javadoc implements Serializable {