From c402592e1b630d271092227ea50bbb35a6d0ecf2 Mon Sep 17 00:00:00 2001 From: Andre601 <11576465+Andre601@users.noreply.github.com> Date: Sat, 4 Jan 2020 17:25:12 +0100 Subject: [PATCH] Merge ReplacedWith into DeprecatedSince --- .github/CONTRIBUTING.md | 13 ++++--- build.gradle | 2 +- .../org/botblock/javabotblockapi/Site.java | 4 +-- .../annotations/DeprecatedSince.java | 9 +++-- .../annotations/ReplacedWith.java | 35 ------------------- 5 files changed, 16 insertions(+), 47 deletions(-) delete mode 100644 src/main/java/org/botblock/javabotblockapi/annotations/ReplacedWith.java diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index d607a850..e4cc1a41 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -33,7 +33,7 @@ Please follow those templates or else your issue might get ignored and closed. We accept pull requests for fixing issues or adding new features, but you have to follow those rules. ### Javadocs -Please add javadocs comments to **all public methods the developer has access to.** +Please add javadocs comments to **all public methods the developer has access to and should use.** Javadocs help developers to see what methods they can/should use and what those do. When adding Javadoc comments, follow this Styling choises. @@ -56,13 +56,15 @@ Do the same for new paragraphs, but keep an empty line in between the text (And Please always use the full path to a class/method when using `{@link}` Bad example: `{@link BotBlockAPI}` -Good example: `{@link BotBlockAPI BotBlockAPI}` +Good example: `{@link org.botblock.javabotblockapi.BotBlockAPI BotBlockAPI}` We want to point out the alternative text used in the Good example, to display "BotBlockAPI" instead of the path. When linking to a method that is in a separate class, set the alternative text to `Class.method(option(s))`. -There is an exception for linking, when you link to a method in the same (inner) class. -In those cases just link to it by using `{@link #methodName}` +If the method you link to is within the same class, use `{@link #methodName() methodName()}`. + +Linking to external Javadoc may be set with the same linking-rules. +New external javadocs may need to be added to the `javadoc` task in the `build.gradle`. **Note**: Use the `` option to link external pages. When doing so also remember to include `target="_blank"`. @@ -112,6 +114,7 @@ Here is an example of the different parts being used: * @deprecated Use {@link #getFooBar() getFooBar()} instead. */ @Deprecated +@DeprecatedSince({"v1.0.1", "#getFooBar"}) // If you deprecate a method, add this one too. public String getFooBar(String foo) throws IllegalArgumentException{ if(foo.isEmpty()) throw new IllegalArgumentException("foo may not be empty"); @@ -134,4 +137,4 @@ public String getFooBar(){ ## [Code of Conduct] We want to give everyone a chance to contribute to the project. So please keep your comments and messages nice. Every message that is considered rasist, insulting or similar will be removed. -If you continue to send those messages you'll be permanently removed from this repository. +If you continue to send those messages will we permanently remove you from this repository. diff --git a/build.gradle b/build.gradle index 8d20932a..3104265c 100644 --- a/build.gradle +++ b/build.gradle @@ -7,7 +7,7 @@ plugins{ id 'com.github.johnrengelman.shadow' version '5.2.0' } -def ver = new Version(major: 4, minor: 0, revision: 4) +def ver = new Version(major: 4, minor: 1, revision: 0) group = "org.botblock" version = "$ver" diff --git a/src/main/java/org/botblock/javabotblockapi/Site.java b/src/main/java/org/botblock/javabotblockapi/Site.java index 277a2990..3636f894 100644 --- a/src/main/java/org/botblock/javabotblockapi/Site.java +++ b/src/main/java/org/botblock/javabotblockapi/Site.java @@ -18,7 +18,6 @@ package org.botblock.javabotblockapi; import org.botblock.javabotblockapi.annotations.DeprecatedSince; -import org.botblock.javabotblockapi.annotations.ReplacedWith; /** * Enum class containing all sites currently supported by BotBlock.org. @@ -67,8 +66,7 @@ public enum Site { *
This option still works, but is no longer supported, nor recommended! */ @Deprecated - @ReplacedWith("TOP_GG") - @DeprecatedSince("v3.0.1") + @DeprecatedSince({"v3.0.1", "#TOP_GG"}) DISCORDBOTS_ORG("discordbots.org"), /** diff --git a/src/main/java/org/botblock/javabotblockapi/annotations/DeprecatedSince.java b/src/main/java/org/botblock/javabotblockapi/annotations/DeprecatedSince.java index 92cb575a..dae92383 100644 --- a/src/main/java/org/botblock/javabotblockapi/annotations/DeprecatedSince.java +++ b/src/main/java/org/botblock/javabotblockapi/annotations/DeprecatedSince.java @@ -22,8 +22,11 @@ /** * Annotation used to indicate since when a method or field is deprecated. - *
This is paired with the {@link java.lang.Deprecated @Deprecated} and the - * {@link org.botblock.javabotblockapi.annotations.ReplacedWith @ReplacedWith} annotation when possible. + *
This is paired with the {@link java.lang.Deprecated @Deprecated} annotation. + * + *

This annotation may have multiple arguments, where first one is the version of deprecation and second one being + * a optional replacement method. + *
Example: {@code @DeprecatedSince({"v1.0.5", "#replacementMethod"})} * * @since v3.2.0 */ @@ -31,5 +34,5 @@ @Retention(RetentionPolicy.RUNTIME) @Target({ElementType.METHOD, ElementType.FIELD}) public @interface DeprecatedSince{ - String value(); + String[] value(); } diff --git a/src/main/java/org/botblock/javabotblockapi/annotations/ReplacedWith.java b/src/main/java/org/botblock/javabotblockapi/annotations/ReplacedWith.java deleted file mode 100644 index ad0de18c..00000000 --- a/src/main/java/org/botblock/javabotblockapi/annotations/ReplacedWith.java +++ /dev/null @@ -1,35 +0,0 @@ -/* - * Copyright 2020 Andre601 - * - * Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated - * documentation files (the "Software"), to deal in the Software without restriction, including without limitation - * the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, - * and to permit persons to whom the Software is furnished to do so, subject to the following conditions: - * - * The above copyright notice and this permission notice shall be included in all copies or substantial - * portions of the Software. - * - * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, - * INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. - * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, - * WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE - * OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. - */ - -package org.botblock.javabotblockapi.annotations; - -import java.lang.annotation.*; - -/** - * Annotation used to indicate a method or field that should be used instead. - *
This is paired with the {@link java.lang.Deprecated @Deprecated} and the - * {@link org.botblock.javabotblockapi.annotations.DeprecatedSince @DeprecatedSince} annotation. - * - * @since v3.2.0 - */ -@Documented -@Retention(RetentionPolicy.RUNTIME) -@Target({ElementType.METHOD, ElementType.FIELD}) -public @interface ReplacedWith{ - String value(); -}