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.
135 lines
2.1 KiB
Plaintext
135 lines
2.1 KiB
Plaintext
== Why is this an issue?
|
|
|
|
Try to imagine using the standard Flex API without ASDoc. It would be a nightmare, because ASDoc is the only way to understand of the contract of the API.
|
|
|
|
Documenting an API with ASDoc increases the productivity of the developers use it.
|
|
|
|
=== Noncompliant code example
|
|
|
|
[source,flex]
|
|
----
|
|
public class MyClass {
|
|
public var myLabel:String;
|
|
|
|
public function myMethod(param1:String):Boolean {...}
|
|
}
|
|
----
|
|
|
|
=== Compliant solution
|
|
|
|
[source,flex]
|
|
----
|
|
/**
|
|
* 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 {...}
|
|
}
|
|
----
|
|
|
|
=== 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
|
|
}
|
|
----
|
|
|
|
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[]
|