Uploaded image for project: 'Rules Repository'
  1. Rules Repository
  2. RSPEC-1176 Public types, methods and fields (API) should be documented
  3. RSPEC-1830

Flex - Public classes, methods, properties and metadata should be documented with ASDoc

    XMLWordPrintable

    Details

    • Type: Language-Specification
    • Status: Active
    • Resolution: Unresolved
    • Labels:
      None
    • Message:
      Hide
      * 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.
      Show
      * 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.
    • List of parameters:
      Hide
      • Key: asdoc_classes
        • Description: Public classes should be documented
        • Default value: true
      • Key: asdoc_properties
        • Description: Public properties should be documented
        • Default value: true
      • Key: asdoc_methods
        • Description: Public methods should be documented
        • Default value: true
      • Key: asdoc_method_param
        • Description: All parameters of public methods should be documented
        • Default value: true
      • Key: asdoc_method_return
        • Description: All return type of public methods should be documented
        • Default value: true
      Show
      Key: asdoc_classes Description: Public classes should be documented Default value: true Key: asdoc_properties Description: Public properties should be documented Default value: true Key: asdoc_methods Description: Public methods should be documented Default value: true Key: asdoc_method_param Description: All parameters of public methods should be documented Default value: true Key: asdoc_method_return Description: All return type of public methods should be documented Default value: true
    • Default Severity:
      Major
    • Impact:
      Low
    • Likelihood:
      High

      Description

      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

      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 {...}
      }
      

      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
      }
      

        Attachments

          Activity

            People

            Assignee:
            Unassigned Unassigned
            Reporter:
            freddy.mallet Freddy Mallet (Inactive)
            Votes:
            0 Vote for this issue
            Watchers:
            1 Start watching this issue

              Dates

              Created:
              Updated: