v3 migration guide for 'Document' removed methods

Fixes #1202
asciidoctor · May 31, 2023 · 1d78b5e · 1d78b5e
1 parent 9862363
commit 1d78b5e
Show file tree

Hide file tree

Showing 3 changed files with 74 additions and 52 deletions.
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)
+----