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.

Why is this an issue?

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.

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.

/**
 * @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

public class MyClass {
  public var myLabel:String;

  public function myMethod(param1:String):Boolean {
    // ...
  }
}

Compliant solution

/**
 * 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

• Technical Writer HQ - How to write API documentation
• FreeCodeCamp - How to write API documentation like a pro