Merge pull request #1211 from abelsromero/issue-1202-remove-deprecate…

…d-from-Document-interface Remove deprecated from Document interface
asciidoctor · Jun 1, 2023 · 9087ec0 · 9087ec0
2 parents 64c1977 + 1d78b5e
commit 9087ec0
Show file tree

Hide file tree

Showing 5 changed files with 93 additions and 97 deletions.
diff --git a/asciidoctorj-api/src/main/java/org/asciidoctor/ast/Document.java b/asciidoctorj-api/src/main/java/org/asciidoctor/ast/Document.java
@@ -17,96 +17,82 @@ public interface Document extends StructuralNode {
      */
     String getDoctitle();
 
-    /**
-     * @deprecated Please use {@link #getDoctitle()}
-     * @return The title as a String.
-     * @see Title
-     */
-    @Deprecated
-    String doctitle();
-
     /**
      * Gets the author(s) information as defined in the author line
      * in the document header, or in author &amp; email attributes.
      *
-     * @return authors information
+     * @return The authors information
+     * @see Author
      */
     List<Author> getAuthors();
 
     /**
      * Make the raw source for the Document available.
      * Trailing white characters (spaces, line breaks, etc.) are removed.
      *
-     * @return raw content as String
+     * @return Raw content as String
      */
     String getSource();
 
     /**
      * Make the raw source lines for the Document available.
      *
-     * @return raw content as List<String>
+     * @return Raw content as List<String>
      */
     List<String> getSourceLines();
 
     /**
-     * @return basebackend attribute value
+     * @return 'basebackend' attribute value
      */
     boolean isBasebackend(String backend);
 
     /**
-     * @deprecated Please use {@link #isBasebackend(String)}
-     * @return basebackend attribute value
-     */
-    @Deprecated
-    boolean basebackend(String backend);
-
-    /**
-     *
-     * @return options defined in document.
+     * @return Options defined in the document
      */
     Map<Object, Object> getOptions();
 
     /**
      * Gets the current counter with the given name and increases its value.
      * At the first invocation the counter will return 1.
      * After the call the value of the counter is set to the returned value plus 1.
-     * @param name
-     * @return
+     *
+     * @param name name of the counter
+     * @return Value before increment plus 1
      */
     int getAndIncrementCounter(String name);
 
     /**
      * Gets the current counter with the given name and increases its value.
      * At the first invocation the counter will return the given initial value.
      * After the call the value of the counter is set to the returned value plus 1.
-     * @param name
-     * @param initialValue
-     * @return
+     *
+     * @param name         name of the counter
+     * @param initialValue value to start counter from
+     * @return Value before increment plus 1
      */
     int getAndIncrementCounter(String name, int initialValue);
 
     /**
-     * @return Whether the sourcemap is enabled.
+     * @return Whether the sourcemap is enabled
      */
     boolean isSourcemap();
 
     /**
      * Toggles the sourcemap option.
-     *
+     * <p>
      * This method must be called before the document is parsed, such as
      * from a Preprocessor extension. Otherwise, it has no effect.
      *
-     * @param state The state in which to put the sourcemap (true = on, false = off).
+     * @param state State in which to put the sourcemap (true = on, false = off)
      */
     void setSourcemap(boolean state);
 
 
     /**
      * The catalog contains data collected by asciidoctor that is useful to a converter.
      *
-     * Note that the catalog is not part of the asciidoctor public API and is subject to change.
-     *
-     * @return catalog
+     * @return Catalog assets
+     * @see Catalog
      */
     Catalog getCatalog();
 
@@ -115,6 +101,7 @@ public interface Document extends StructuralNode {
      * The revision information with: date, number and remark.
      *
      * @return revisionInfo
+     * @see RevisionInfo
      */
     RevisionInfo getRevisionInfo();
 }
diff --git a/asciidoctorj-core/src/main/java/org/asciidoctor/jruby/ast/impl/DocumentImpl.java b/asciidoctorj-core/src/main/java/org/asciidoctor/jruby/ast/impl/DocumentImpl.java
@@ -31,12 +31,6 @@ public boolean isBasebackend(String backend) {
         return getBoolean("basebackend?", backend);
     }
 
-    @Override
-    @Deprecated
-    public boolean basebackend(String backend) {
-        return isBasebackend(backend);
-    }
-
     @Override
     public Map<Object, Object> getOptions() {
         return RubyHashUtil.convertRubyHashMapToMap((RubyHash) getRubyProperty("options"));
@@ -52,20 +46,13 @@ public Title getStructuredDoctitle() {
         Object doctitle = getRubyProperty("doctitle", options);
 
         return toJava((IRubyObject) doctitle, Title.class);
-
     }
 
     @Override
     public String getDoctitle() {
         return getString("doctitle");
     }
 
-    @Override
-    @Deprecated
-    public String doctitle() {
-        return getDoctitle();
-    }
-
     @Override
     public List<Author> getAuthors() {
         return getList("authors", RubyStruct.class)

diff --git a/docs/modules/guides/pages/api-migration-guide-v25x-to-v30.adoc b/docs/modules/guides/pages/api-migration-guide-v25x-to-v30.adoc
@@ -4,62 +4,16 @@
 AsciidoctorJ v3.0.0 introduces breaking changes.
 This guide will provide the steps required to update a project currently using 2.5.x version.
 
-include::partial$removal-of-deprecated-methods-in-options.adoc[]
-
-include::partial$removal-of-deprecated-methods-in-attributes.adoc[]
-
-== Removal of `asMap` from OptionsBuilder and AttributesBuilder
-
-In v2.5.x it is possible to obtain the backing `Map<String,Object>` for both options and attributes.
-
-[,java]
-.Obtaining backing Map for OptionsBuilder
-----
-Map<String, Object> optionsMap = Options.builder()
-    .backend("html5")
-    .mkDirs(true)
-    .safe(SafeMode.UNSAFE)
-    .asMap();
-----
-
-[,java]
-.Obtaining backing Map for AttributesBuilder
-----
-Map<String, Object> attributesMap = Attributes.builder()
-    .icons("font")
-    .sectionNumbers(true)
-    .asMap();
-----
-
-To remove feature duplication and avoid confusion between values in the actual `org.asciidoctor.Attributes` and `org.asciidoctor.Options` and their respective builders, `asMap` it's no longer available in both builders.
+include::partial$update-preprocessor-api.adoc[]
 
-To obtain the backing up, use the `map()` method from the actual `org.asciidoctor.Attributes` and `org.asciidoctor.Options` instances.
+include::partial$update-macro-api.adoc[]
 
-IMPORTANT: `Options::map()` and `Attributes::map()` are marked as deprecated and subject to change at some point, but are still maintained and safe to use in v3.0.x.
+include::partial$removal-of-deprecated-methods-in-options.adoc[]
 
-[,java]
-.Obtaining backing Map for Options
-----
-Options options = Options.builder()
-    .backend("html5")
-    .mkDirs(true)
-    .safe(SafeMode.UNSAFE)
-    .build();
-Map<String, Object> optionsMap = options.map();
-----
+include::partial$removal-of-deprecated-methods-in-attributes.adoc[]
 
-[,java]
-.Obtaining backing Map for Attributes
-----
-Attributes attributes = Attributes.builder()
-    .icons("font")
-    .sectionNumbers(true)
-    .build();
-Map<String, Object> attributesMap = attributes.map();
-----
+include::partial$removal-of-deprecated-asMap-from-builders.adoc[]
 
 include::partial$removal-of-deprecated-methods-in-asciidoctor.adoc[]
 
-include::partial$update-preprocessor-api.adoc[]
-
-include::partial$update-macro-api.adoc[]
+include::partial$removal-of-deprecated-methods-in-document.adoc[]
diff --git a/docs/modules/guides/partials/removal-of-deprecated-asMap-from-builders.adoc b/docs/modules/guides/partials/removal-of-deprecated-asMap-from-builders.adoc
@@ -0,0 +1,49 @@
+== Removal of `asMap` from OptionsBuilder and AttributesBuilder
+
+In v2.5.x it is possible to obtain the backing `Map<String,Object>` for both options and attributes.
+
+[,java]
+.Obtaining backing Map for OptionsBuilder
+----
+Map<String, Object> optionsMap = Options.builder()
+    .backend("html5")
+    .mkDirs(true)
+    .safe(SafeMode.UNSAFE)
+    .asMap();
+----
+
+[,java]
+.Obtaining backing Map for AttributesBuilder
+----
+Map<String, Object> attributesMap = Attributes.builder()
+    .icons("font")
+    .sectionNumbers(true)
+    .asMap();
+----
+
+To remove feature duplication and avoid confusion between values in the actual `org.asciidoctor.Attributes` and `org.asciidoctor.Options` and their respective builders, `asMap` it's no longer available in both builders.
+
+To obtain the backing up, use the `map()` method from the actual `org.asciidoctor.Attributes` and `org.asciidoctor.Options` instances.
+
+IMPORTANT: `Options::map()` and `Attributes::map()` are marked as deprecated and subject to change at some point, but are still maintained and safe to use in v3.0.x.
+
+[,java]
+.Obtaining backing Map for Options
+----
+Options options = Options.builder()
+    .backend("html5")
+    .mkDirs(true)
+    .safe(SafeMode.UNSAFE)
+    .build();
+Map<String, Object> optionsMap = options.map();
+----
+
+[,java]
+.Obtaining backing Map for Attributes
+----
+Attributes attributes = Attributes.builder()
+    .icons("font")
+    .sectionNumbers(true)
+    .build();
+Map<String, Object> attributesMap = attributes.map();
+----
diff --git a/docs/modules/guides/partials/removal-of-deprecated-methods-in-document.adoc b/docs/modules/guides/partials/removal-of-deprecated-methods-in-document.adoc
@@ -0,0 +1,19 @@
+== Removal of deprecated methods in `org.asciidoctor.ast.Document`
+
+Several methods in `org.asciidoctor.ast.Document` that were marked as `@Deprecated` have been removed.
+
+For each of the removed methods, the equivalent can be found below.
+
+[,java]
+.Removed deprecated methods
+----
+String doctitle()
+boolean basebackend(String backend)
+----
+
+[,java]
+.Final methods
+----
+String getDoctitle()
+boolean isBasebackend(String backend)
+----