154 lines
2.4 KiB
Plaintext
154 lines
2.4 KiB
Plaintext
include::../introduction.adoc[]
|
|
|
|
== Why is this an issue?
|
|
|
|
include::../why-is-this-an-issue.adoc[]
|
|
|
|
It is recommended to document the API using *ASDoc* to clarify what is the contract of the API.
|
|
This is especially important for public APIs, as they are used by other developers.
|
|
|
|
=== Exceptions
|
|
|
|
Classes or class elements with an ASDoc ``++@private++`` comment are ignored by this rule.
|
|
|
|
[source,flex]
|
|
----
|
|
/**
|
|
* @private // This class and all its elements are ignored
|
|
*/
|
|
public class MyClass { // Compliant
|
|
|
|
public var myLabel:String; // Compliant
|
|
}
|
|
|
|
public class AnotherClass { // Noncompliant; class not @private and not documented
|
|
|
|
/**
|
|
* @private
|
|
*/
|
|
public var name:String; // Compliant
|
|
}
|
|
----
|
|
|
|
== How to fix it
|
|
|
|
Add the missing *ASDoc* for the public classes, methods, properties and metadata.
|
|
|
|
=== Code examples
|
|
|
|
==== Noncompliant code example
|
|
|
|
[source,flex,diff-id=1,diff-type=noncompliant]
|
|
----
|
|
public class MyClass {
|
|
public var myLabel:String;
|
|
|
|
public function myMethod(param1:String):Boolean {
|
|
// ...
|
|
}
|
|
}
|
|
----
|
|
|
|
==== Compliant solution
|
|
|
|
[source,flex,diff-id=1,diff-type=compliant]
|
|
----
|
|
/**
|
|
* my doc
|
|
*/
|
|
public class MyClass {
|
|
/**
|
|
* my doc
|
|
*/
|
|
public var myLabel:String;
|
|
|
|
/**
|
|
* my doc
|
|
* @param param1 my doc
|
|
* @return my doc
|
|
*/
|
|
public function myMethod(param1:String):Boolean {
|
|
// ...
|
|
}
|
|
}
|
|
----
|
|
|
|
== Resources
|
|
|
|
=== Articles & blog posts
|
|
|
|
include::../articles-and-blog-posts.adoc[]
|
|
|
|
|
|
ifdef::env-github,rspecator-view[]
|
|
|
|
'''
|
|
== Implementation Specification
|
|
(visible only on this page)
|
|
|
|
=== Message
|
|
|
|
* Add the missing ASDoc for this class.
|
|
* Add the missing ASDoc for this field declaration.
|
|
* Add the missing ASDoc for this method.
|
|
* Add the missing "@param" ASDoc for: {0}.
|
|
* Add the missing "@return" ASDoc for the return value of this method.
|
|
|
|
|
|
=== Parameters
|
|
|
|
.asdoc_classes
|
|
****
|
|
|
|
----
|
|
true
|
|
----
|
|
|
|
Public classes should be documented
|
|
****
|
|
.asdoc_properties
|
|
****
|
|
|
|
----
|
|
true
|
|
----
|
|
|
|
Public properties should be documented
|
|
****
|
|
.asdoc_methods
|
|
****
|
|
|
|
----
|
|
true
|
|
----
|
|
|
|
Public methods should be documented
|
|
****
|
|
.asdoc_method_param
|
|
****
|
|
|
|
----
|
|
true
|
|
----
|
|
|
|
All parameters of public methods should be documented
|
|
****
|
|
.asdoc_method_return
|
|
****
|
|
|
|
----
|
|
true
|
|
----
|
|
|
|
All return type of public methods should be documented
|
|
****
|
|
|
|
|
|
'''
|
|
== Comments And Links
|
|
(visible only on this page)
|
|
|
|
include::../comments-and-links.adoc[]
|
|
|
|
endif::env-github,rspecator-view[]
|