From 986236356aba26c9300c69b63c53778ce435b545 Mon Sep 17 00:00:00 2001 From: Abel Salgado Romero Date: Mon, 22 May 2023 21:25:31 +0200 Subject: [PATCH 1/2] Remove deprecated methods from Document interface * Improved 'org.asciidoctor.ast.Document' Javadocs Fixes #1202 --- .../java/org/asciidoctor/ast/Document.java | 51 +++++++------------ .../jruby/ast/impl/DocumentImpl.java | 13 ----- 2 files changed, 19 insertions(+), 45 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 index 86cbbff9c..faab0889c 100644 --- a/asciidoctorj-api/src/main/java/org/asciidoctor/ast/Document.java +++ b/asciidoctorj-api/src/main/java/org/asciidoctor/ast/Document.java @@ -17,19 +17,12 @@ 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 & email attributes. * - * @return authors information + * @return The authors information + * @see Author */ List getAuthors(); @@ -37,32 +30,24 @@ public interface Document extends StructuralNode { * 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 + * @return Raw content as List */ List 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 getOptions(); @@ -70,8 +55,9 @@ public interface Document extends StructuralNode { * 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); @@ -79,24 +65,25 @@ public interface Document extends StructuralNode { * 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. - * + *

* 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); @@ -104,9 +91,8 @@ public interface Document extends StructuralNode { /** * 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 index d4f7497c6..bad3b2f51 100644 --- 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 getOptions() { return RubyHashUtil.convertRubyHashMapToMap((RubyHash) getRubyProperty("options")); @@ -52,7 +46,6 @@ public Title getStructuredDoctitle() { Object doctitle = getRubyProperty("doctitle", options); return toJava((IRubyObject) doctitle, Title.class); - } @Override @@ -60,12 +53,6 @@ public String getDoctitle() { return getString("doctitle"); } - @Override - @Deprecated - public String doctitle() { - return getDoctitle(); - } - @Override public List getAuthors() { return getList("authors", RubyStruct.class) From 1d78b5e0694419c150f60c88ddf56e1723cd4bec Mon Sep 17 00:00:00 2001 From: Abel Salgado Romero Date: Mon, 22 May 2023 23:01:35 +0200 Subject: [PATCH 2/2] v3 migration guide for 'Document' removed methods Fixes #1202 --- .../api-migration-guide-v25x-to-v30.adoc | 58 ++----------------- ...val-of-deprecated-asMap-from-builders.adoc | 49 ++++++++++++++++ ...val-of-deprecated-methods-in-document.adoc | 19 ++++++ 3 files changed, 74 insertions(+), 52 deletions(-) create mode 100644 docs/modules/guides/partials/removal-of-deprecated-asMap-from-builders.adoc create mode 100644 docs/modules/guides/partials/removal-of-deprecated-methods-in-document.adoc 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 index d0c62f525..3ecc4160a 100644 --- 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` for both options and attributes. - -[,java] -.Obtaining backing Map for OptionsBuilder ----- -Map optionsMap = Options.builder() - .backend("html5") - .mkDirs(true) - .safe(SafeMode.UNSAFE) - .asMap(); ----- - -[,java] -.Obtaining backing Map for AttributesBuilder ----- -Map 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 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 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 new file mode 100644 index 000000000..034f5873a --- /dev/null +++ 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` for both options and attributes. + +[,java] +.Obtaining backing Map for OptionsBuilder +---- +Map optionsMap = Options.builder() + .backend("html5") + .mkDirs(true) + .safe(SafeMode.UNSAFE) + .asMap(); +---- + +[,java] +.Obtaining backing Map for AttributesBuilder +---- +Map 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 optionsMap = options.map(); +---- + +[,java] +.Obtaining backing Map for Attributes +---- +Attributes attributes = Attributes.builder() + .icons("font") + .sectionNumbers(true) + .build(); +Map 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 new file mode 100644 index 000000000..a1b8548c5 --- /dev/null +++ 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) +----