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

PHP: Files, classes, functions and variables should be documented

    XMLWordPrintable

    Details

    • Type: Language-Specification
    • Status: Active
    • Resolution: Unresolved
    • Labels:
      None
    • Message:
      Hide
      * Add the missing documentation for this (file|class|function|variable).
      * Add the missing "@return" tag for this function.
      * Add the missing "@throws" tag for this function.
      * Add the missing "@param" tag for "XXX".
      * Add the missing "@var" tag for this variable.
      Show
      * Add the missing documentation for this (file|class|function|variable). * Add the missing "@return" tag for this function. * Add the missing "@throws" tag for this function. * Add the missing "@param" tag for "XXX". * Add the missing "@var" tag for this variable.
    • List of parameters:
      Hide
      • key: file
        • description: Require documentation of files
        • default: true
      • key: class
        • description: Require documentation of classes
        • default: true
      • key: function
        • description: Require documentation of functions
        • default: true
      • key: throws_tag
        • description: Require an "@throws" tag where appropriate
        • default: true
      • key: return_tag
        • description: Require an "@return" tag
        • default: true
      • key: param_tag
        • description: Require an "@param" tag for each function parameter
        • default: true
      • key: variables
        • description: Require documentation of variables
        • default: true
      • key: var_tag
        • description: Require that variable documentation contain an "@var" tag
        • default: true
      Show
      key: file description: Require documentation of files default: true key: class description: Require documentation of classes default: true key: function description: Require documentation of functions default: true key: throws_tag description: Require an "@throws" tag where appropriate default: true key: return_tag description: Require an "@return" tag default: true key: param_tag description: Require an "@param" tag for each function parameter default: true key: variables description: Require documentation of variables default: true key: var_tag description: Require that variable documentation contain an "@var" tag default: true
    • Impact:
      Unknown 'null' severity
    • Likelihood:
      Unknown 'null' severity

      Description

      Noncompliant Code Example

      <?php  // Noncompliant; file comment missing
      class MyClass   // Noncompliant; undocumented
      {
      
        $prop; // Noncompliant
      
        /**
         * Variable comment.
         */
        $prop2;  // Noncompliant; variable comment present, but @var tag missing
      
        protected $name, $description;  // Noncompliant
      
        function doSomething($param)  // Noncompliant
        {
          // ...
          if ($vogons) {
              throw new Exception('Help!.');
          }
      
          return 42;
        }
      }
      

      Compliant Solution

      <?php
      /**
       * This is a file comment. There is vertical whitespace 
       * between it and the next element.
       */
      
      /** 
       * MyClass does something interesting...
       */
      class MyClass
      {
        /**
         * Holds the vault combination
         * @var string 
         */
        $prop;
      
        /**
         * Variable comment.
         * @var number
         */
        $prop2;
      
        /** 
         *  @var string $name
         *  @var string $description
         */
        protected $name, $description;
      
        /**
         * Calculates the answer to a question
         *
         * @param string   The question
         *
         * @throws exception  If Vogons encountered
         *
         * @return integer  Returns the answer to life, the universe and everything
         */
        function doSomething($param)  // Noncompliant
        {
          // ...
          if ($vogons) {
              throw new Exception('Help!.');
          }
      
          return 42;
        }
      }
      

        Attachments

          Activity

            People

            Assignee:
            Unassigned Unassigned
            Reporter:
            ann.campbell.2 Ann Campbell
            Votes:
            2 Vote for this issue
            Watchers:
            3 Start watching this issue

              Dates

              Created:
              Updated: