From 99ee12dc7c1d5ba4662bccc81b66016ccdda52ad Mon Sep 17 00:00:00 2001 From: Maxim Muzafarov Date: Thu, 12 Oct 2023 15:59:13 +0200 Subject: [PATCH 1/2] CASSANDRA-18912 Update code style documentation for deprecation rules --- .../ROOT/pages/development/code_style.adoc | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/site-content/source/modules/ROOT/pages/development/code_style.adoc b/site-content/source/modules/ROOT/pages/development/code_style.adoc index 2e9e97077..6d6a7406a 100644 --- a/site-content/source/modules/ROOT/pages/development/code_style.adoc +++ b/site-content/source/modules/ROOT/pages/development/code_style.adoc @@ -1,5 +1,6 @@ = Code Style :page-layout: basic +:toc: The Cassandra project follows http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html[Sun's Java @@ -176,3 +177,21 @@ https://gist.github.com/jdsumsion/9ab750a05c2a567c6afc[gist for IntelliJ 13] (this is a work in progress, still working on javadoc, ternary style, line continuations, etc) * Eclipse: (https://github.com/tjake/cassandra-style-eclipse) + +== JavaDoc + +=== Deprecation + +To deprecate the old API, we use one of the built-in annotations of the Java language, the `@Deprecated` annotation with a `since` annotation element that points to the version since the API was deprecated. We always use it in conjunction with the `@deprecated` Javadoc tag, which describes the reason for the deprecation and an alternative, if applicable. A JIRA ticket is also worth mentioning in the deprecation message. All of these rules are enforced by the checkstyle. + +Consider the following examples: + +[source,java] +---- +/** @deprecated Migrate to {@link DatabaseDescriptor#isClientInitialized()}. See CASSANDRA-1255 */ +@Deprecated(since = "3.10") +public static boolean isClientMode() +{ + return isClientMode; +} +---- \ No newline at end of file From 8f7e37773bbc5198d6db03fd07ed7d367a582b2e Mon Sep 17 00:00:00 2001 From: Maxim Muzafarov Date: Thu, 12 Oct 2023 16:24:13 +0200 Subject: [PATCH 2/2] fix table of contents --- .../source/modules/ROOT/pages/development/code_style.adoc | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/site-content/source/modules/ROOT/pages/development/code_style.adoc b/site-content/source/modules/ROOT/pages/development/code_style.adoc index 6d6a7406a..d5ed3d00d 100644 --- a/site-content/source/modules/ROOT/pages/development/code_style.adoc +++ b/site-content/source/modules/ROOT/pages/development/code_style.adoc @@ -1,6 +1,5 @@ = Code Style :page-layout: basic -:toc: The Cassandra project follows http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html[Sun's Java @@ -194,4 +193,4 @@ public static boolean isClientMode() { return isClientMode; } ----- \ No newline at end of file +----