51369b610e
When an include is not surrounded by empty lines, its content is inlined on the same line as the adjacent content. That can lead to broken tags and other display issues. This PR fixes all such includes and introduces a validation step that forbids introducing the same problem again.
89 lines
1.5 KiB
Plaintext
89 lines
1.5 KiB
Plaintext
== Why is this an issue?
|
|
|
|
Deprecation should be marked with both the ``++@Deprecated++`` annotation and @deprecated Javadoc tag. The annotation enables tools such as IDEs to warn about referencing deprecated elements, and the tag can be used to explain when it was deprecated, why, and how references should be refactored.
|
|
|
|
|
|
=== Noncompliant code example
|
|
|
|
[source,java]
|
|
----
|
|
class MyClass {
|
|
|
|
@Deprecated
|
|
public void foo1() { // Noncompliant: Add the missing @deprecated Javadoc tag.
|
|
}
|
|
|
|
/**
|
|
* @deprecated
|
|
*/
|
|
public void foo2() { // Noncompliant: Add the missing @Deprecated annotation.
|
|
}
|
|
|
|
}
|
|
----
|
|
|
|
|
|
=== Compliant solution
|
|
|
|
[source,java]
|
|
----
|
|
class MyClass {
|
|
|
|
/**
|
|
* @deprecated (when, why, refactoring advice...)
|
|
*/
|
|
@Deprecated
|
|
public void foo1() {
|
|
}
|
|
|
|
}
|
|
----
|
|
|
|
|
|
=== Exceptions
|
|
|
|
The members and methods of a deprecated class or interface are ignored by this rule. The classes and interfaces themselves are still subject to it.
|
|
|
|
|
|
[source,java]
|
|
----
|
|
/**
|
|
* @deprecated (when, why, etc...)
|
|
*/
|
|
@Deprecated
|
|
class Qix {
|
|
|
|
public void foo() {} // Compliant; class is deprecated
|
|
|
|
}
|
|
|
|
/**
|
|
* @deprecated (when, why, etc...)
|
|
*/
|
|
@Deprecated
|
|
interface Plop {
|
|
|
|
void bar();
|
|
|
|
}
|
|
----
|
|
|
|
ifdef::env-github,rspecator-view[]
|
|
|
|
'''
|
|
== Implementation Specification
|
|
(visible only on this page)
|
|
|
|
=== Message
|
|
|
|
Add the missing [@Deprecated annotation | @deprecated Javadoc tag].
|
|
|
|
|
|
'''
|
|
== Comments And Links
|
|
(visible only on this page)
|
|
|
|
include::../comments-and-links.adoc[]
|
|
|
|
endif::env-github,rspecator-view[]
|