Modify rule S1176: Migrate to LayC - Public types, methods and field …

…(API) should be documented (#3307)

Co-authored-by: Peter Trifanov <[email protected]>

rules/S1176/articles-and-blog-posts.adoc

@@ -0,0 +1,2 @@
+* Technical Writer HQ - https://technicalwriterhq.com/documentation/api-documentation/how-to-write-api-documentation/[How to write API documentation]
+* FreeCodeCamp - https://www.freecodecamp.org/news/how-to-write-api-documentation-like-a-pro/[How to write API documentation like a pro]

rules/S1176/flex/rule.adoc

@@ -1,23 +1,57 @@
+include::../introduction.adoc[]
+
 == 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.
+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.
 
-Documenting an API with ASDoc increases the productivity of the developers use it.
+=== Exceptions
 
-=== Noncompliant code example
+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 {...}
+  public function myMethod(param1:String):Boolean {
+    // ...
+  }
 }
 ----
 
-=== Compliant solution
+==== Compliant solution
 
-[source,flex]
+[source,flex,diff-id=1,diff-type=compliant]
 ----
 /**
  * my doc
@@ -33,33 +67,18 @@ public class MyClass {
    * @param param1 my doc
    * @return my doc
    */
-  public function myMethod(param1:String):Boolean {...}
+  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
+== Resources
 
-  public var myLabel:String;   // Compliant
-}
+=== Articles & blog posts
 
-public class AnotherClass {  // Noncompliant; class not @private and not documented
+include::../articles-and-blog-posts.adoc[]
 
-  /** 
-   * @private
-   */
-  public var name:String;  // Compliant
-}
-----
 
 ifdef::env-github,rspecator-view[]
 

rules/S1176/introduction.adoc

@@ -0,0 +1,2 @@
+A good API documentation is a key factor in the usability and success of a software API.
+It ensures that developers can effectively use, maintain, and collaborate on the API.

rules/S1176/java/rule.adoc

@@ -1,92 +1,101 @@
-== Why is this an issue?
-
-Try to imagine using the standard Java API (Collections, JDBC, IO, ...) without Javadoc. It would be a nightmare, because Javadoc is the only way to understand of the contract of the API. Documenting an API with Javadoc increases the productivity of the developers consuming it.
-
+include::../introduction.adoc[]
 
-On top of a main description for each member of a public API, the following Javadoc elements are required to be described:
+== Why is this an issue?
 
-* Parameters, using ``++@param parameterName++``.
-* Thrown exceptions, using ``++@throws exceptionName++``.
-* Method return values, using ``++@return++``.
-* Generic types, using ``++@param <T>++``.
+include::../why-is-this-an-issue.adoc[]
 
-Furthermore the following guidelines should be followed:
+It is recommended to document the API using *JavaDoc* to clarify what is the contract of the API.
+This is especially important for public APIs, as they are used by other developers.
 
-* At least 1 line of description.
-* All parameters documented with ``++@param++``, and names should match.
-* All checked exceptions documented with ``++@throws++``
-* ``++@return++`` present and documented when not ``++void++``.
-* Placeholders like ``++"TODO"++``, ``++"FIXME"++``, ``++"..."++`` should be avoided.
+=== Exceptions
 
 The following public methods and constructors are not taken into account by this rule:
 
 * Getters and setters.
-* Methods overriding another method (usually decorated with ``++@Override++``).
+* Methods overriding another method (usually annotated with `@Override`).
 * Empty constructors.
 * Static constants.
 
-For the parameters of the rule, the following rules are applied:
+== How to fix it
+
+On top of a main description for each member of a public API, the following *Javadoc* elements are required to be described:
+
+* Parameters, using `@param parameterName`.
+* Thrown exceptions, using `@throws exceptionName`.
+* Method return values, using `@return`.
+* Generic types, using `@param <T>`.
+
+Furthermore, the following guidelines should be followed:
+
+* At least 1 line of description.
+* All parameters documented with `@param`, and names should match.
+* All checked exceptions should be documented with `@throws`
+* `@return` present and documented when method return type is not `void`.
+* Placeholders like `"TODO"`, `"FIXME"`, `"..."` should be avoided.
 
+For the parameters of the rule, the following rules are applied:
 
-* ``++?++`` matches a single character
-* ``++*++`` matches zero or more characters
-* ``++**++`` matches zero or more packages
+* `?` matches a single character
+* `*` matches zero or more characters
+* `**` matches zero or more packages
 
 Examples:
 
-* ``++java.internal.InternalClass++`` will match only ``++InternalClass++`` class.
-* ``++java.internal.*++`` will match any member of ``++java.internal++`` package.
-* ``++java.internal.**++`` same as above, but including sub-packages.
+* `java.internal.InternalClass` will match only `InternalClass` class.
+* `java.internal.*` will match any member of `java.internal` package.
+* `java.internal.**` same as above, but including sub-packages.
+
+=== Code examples
 
-=== Noncompliant code example
+==== Noncompliant code example
 
-[source,java]
+[source,java,diff-id=1,diff-type=noncompliant]
 ----
 /**
   * This is a Javadoc comment
   */
-public class MyClass<T> implements Runnable {    // Noncompliant - missing '@param <T>'
+public class MyClass<T> implements Runnable {   // Noncompliant - missing '@param <T>'
 
-  public static final DEFAULT_STATUS = 0;    // Compliant - static constant
+  public static final int DEFAULT_STATUS = 0;   // Compliant - static constant
   private int status;                           // Compliant - not public
 
-  public String message;                  // Noncompliant
+  public String message;                        // Noncompliant
 
-  public MyClass() {                         // Noncompliant - missing documentation
+  public MyClass() {                            // Noncompliant - missing documentation
     this.status = DEFAULT_STATUS;
   }
 
-  public void setStatus(int status) {  // Compliant - setter
+  public void setStatus(int status) {           // Compliant - setter
     this.status = status;
   }
 
   @Override
-  public void run() {                          // Compliant - has @Override annotation
+  public void run() {                           // Compliant - has @Override annotation
   }
 
-  protected void doSomething() {    // Compliant - not public
+  protected void doSomething() {                // Compliant - not public
   }
 
-  public void doSomething2(int value) {  // Noncompliant
+  public void doSomething2(int value) {         // Noncompliant
   }
 
-  public int doSomething3(int value) {  // Noncompliant
+  public int doSomething3(int value) {          // Noncompliant
     return value;
   }
 }
 ----
 
-=== Compliant solution
+==== Compliant solution
 
-[source,java]
+[source,java,diff-id=1,diff-type=compliant]
 ----
 /**
   * This is a Javadoc comment
   * @param <T> the parameter of the class
   */
 public class MyClass<T> implements Runnable {
 
-  public static final DEFAULT_STATUS = 0;
+  public static final int DEFAULT_STATUS = 0;
   private int status;
 
   /**
@@ -117,6 +126,7 @@ public class MyClass<T> implements Runnable {
     * @param value the value to be used
     */
   public void doSomething(int value) {
+  }
 
   /**
     *  {@inheritDoc}
@@ -127,6 +137,17 @@ public class MyClass<T> implements Runnable {
 }
 ----
 
+== Resources
+
+=== Documentation
+
+* Oracle - https://docs.oracle.com/javase/8/docs/technotes/tools/windows/javadoc.html[JavaDoc]
+
+=== Articles & blog posts
+
+include::../articles-and-blog-posts.adoc[]
+
+
 ifdef::env-github,rspecator-view[]
 
 '''

rules/S1176/php/rule.adoc

@@ -1,28 +1,38 @@
+include::../introduction.adoc[]
+
 == Why is this an issue?
 
+include::../why-is-this-an-issue.adoc[]
+
 Try to imagine using a standard library without documentation.
 
-It would be a nightmare, because documentation is the only way to understand of the contract of the API. Documenting an API  increases the productivity of the developers consuming it.
+It is recommended to document the API to clarify what is the contract of the API.
+This is especially important for public APIs, as they are used by other developers.
+
+== How to fix it
+
+Add the missing documentation for the files, classes, functions and variables.
 
+=== Code examples
 
-=== Noncompliant code example
+==== Noncompliant code example
 
-[source,php]
+[source,php,diff-id=1,diff-type=noncompliant]
 ----
-<?php  // Noncompliant; file comment missing
-class MyClass   // Noncompliant; undocumented
+<?php                               // Noncompliant; file comment missing
+class MyClass                       // Noncompliant; undocumented
 {
 
-  $prop; // Noncompliant
+  $prop;                            // Noncompliant
 
   /**
    * Variable comment.
    */
-  $prop2;  // Noncompliant; variable comment present, but @var tag missing
+  $prop2;                           // Noncompliant; variable comment present, but @var tag missing
 
-  protected $name, $description;  // Noncompliant
+  protected $name, $description;    // Noncompliant
 
-  function doSomething($param)  // Noncompliant
+  function doSomething($param)      // Noncompliant
   {
     // ...
     if ($vogons) {
@@ -34,9 +44,9 @@ class MyClass   // Noncompliant; undocumented
 }
 ----
 
-=== Compliant solution
+==== Compliant solution
 
-[source,php]
+[source,php,diff-id=1,diff-type=compliant]
 ----
 <?php
 /**
@@ -76,7 +86,7 @@ class MyClass
    *
    * @return integer  Returns the answer to life, the universe and everything
    */
-  function doSomething($param)  // Noncompliant
+  function doSomething($param)
   {
     // ...
     if ($vogons) {
@@ -88,6 +98,13 @@ class MyClass
 }
 ----
 
+== Resources
+
+=== Articles & blog posts
+
+include::../articles-and-blog-posts.adoc[]
+
+
 ifdef::env-github,rspecator-view[]
 
 '''

rules/S1176/why-is-this-an-issue.adoc

@@ -0,0 +1,12 @@
+Undocumented APIs pose significant challenges in software development for several reasons:
+
+* *Lack of Clarity:* developers struggling to understand how to use the API correctly. This can lead to misuse and unexpected results.
+
+* *Increased Development Time:* developers spending extra time reading and understanding the source code, which slows down the development process.
+
+* *Error Prone:* developers are more likely to make mistakes that lead to bugs or system crashes when the intent or the error handling of an API is not clear.
+
+* *Difficult Maintenance and Updates:* developers may not understand the existing functionality well enough to add new features without breaking the existing ones.
+
+* *Poor Collaboration:* collaboration, when there is lack of documentation, leads to confusion and inconsistencies.
+