rspec/rules/S1176/flex/rule.adoc

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[]