Merge pull request moodlehq#142 from andrewnicols/removeDocblockDescriptions

Remove phpdocsfistline and functiondescription (moodlehq#142)

Author: stronk7

file.php

@@ -1267,20 +1267,6 @@ public function get_original_token_id() {
         return $this->originaltid;
     }
 
-    /**
-     * Returns short description found in phpdocs if found (first line followed by empty line)
-     *
-     * @return string
-     */
-    public function get_shortdescription() {
-        $lines = preg_split('/\n/', $this->description);
-        if (count($lines) == 1 || (count($lines) && !strlen(trim($lines[1])))) {
-            return $lines[0];
-        } else {
-            return false;
-        }
-    }
-
     /**
      * Returns list of parsed param tokens found in phpdocs
      *

lang/en/local_moodlecheck.php

@@ -43,9 +43,6 @@
 $string['rule_noinlinephpdocs'] = 'There are no comments starting with three or more slashes';
 $string['error_noinlinephpdocs'] = 'Found comment starting with three or more slashes';
 
-$string['error_phpdocsfistline'] = 'No one-line description found in phpdocs for <b>{$a->object}</b>';
-$string['rule_phpdocsfistline'] = 'File-level phpdocs block and class phpdocs should have one-line short description';
-
 $string['error_phpdocsinvalidinlinetag'] = 'Invalid inline phpdocs tag <b>{$a->tag}</b> found';
 $string['rule_phpdocsinvalidinlinetag'] = 'Inline phpdocs tags are valid';
 
@@ -55,9 +52,6 @@
 $string['error_phpdoccontentsinlinetag'] = 'Inline phpdocs tag <b>{$a->tag}</b> with incorrect contents found. It must match {@link [valid URL] [description (optional)]} or {@see [valid FQSEN] [description (optional)]}';
 $string['rule_phpdoccontentsinlinetag'] = 'Inline phpdocs tags have correct contents';
 
-$string['error_functiondescription'] = 'There is no description in phpdocs for function <b>{$a->object}</b>';
-$string['rule_functiondescription'] = 'Functions have descriptions in phpdocs';
-
 $string['error_functionarguments'] = 'Phpdocs for function <b>{$a->function}</b> has incomplete parameters list';
 $string['rule_functionarguments'] = 'Phpdocs for functions properly define all parameters';
 

rules/phpdocs_basic.php

@@ -26,8 +26,6 @@
 
 local_moodlecheck_registry::add_rule('definesdocumented')->set_callback('local_moodlecheck_definesdocumented');
 local_moodlecheck_registry::add_rule('noinlinephpdocs')->set_callback('local_moodlecheck_noinlinephpdocs');
-local_moodlecheck_registry::add_rule('phpdocsfistline')->set_callback('local_moodlecheck_phpdocsfistline');
-local_moodlecheck_registry::add_rule('functiondescription')->set_callback('local_moodlecheck_functiondescription');
 local_moodlecheck_registry::add_rule('functionarguments')->set_callback('local_moodlecheck_functionarguments');
 local_moodlecheck_registry::add_rule('definedoccorrect')->set_callback('local_moodlecheck_definedoccorrect');
 local_moodlecheck_registry::add_rule('phpdocsinvalidinlinetag')->set_callback('local_moodlecheck_phpdocsinvalidinlinetag');
@@ -159,51 +157,6 @@ function local_moodlecheck_phpdoccontentsinlinetag(local_moodlecheck_file $file)
     return $errors;
 }
 
-/**
- * Makes sure that file-level phpdocs and all classes have one-line short description
- *
- * @param local_moodlecheck_file $file
- * @return array of found errors
- */
-function local_moodlecheck_phpdocsfistline(local_moodlecheck_file $file) {
-    $errors = [];
-
-    if (($phpdocs = $file->find_file_phpdocs()) && !$file->find_file_phpdocs()->get_shortdescription()) {
-        $errors[] = [
-            'line' => $phpdocs->get_line_number($file),
-            'object' => 'file',
-        ];
-    }
-    foreach ($file->get_classes() as $class) {
-        if ($class->phpdocs && !$class->phpdocs->get_shortdescription()) {
-            $errors[] = [
-                'line' => $class->phpdocs->get_line_number($file),
-                'object' => 'class '.$class->name,
-            ];
-        }
-    }
-    return $errors;
-}
-
-/**
- * Makes sure that all functions have descriptions
- *
- * @param local_moodlecheck_file $file
- * @return array of found errors
- */
-function local_moodlecheck_functiondescription(local_moodlecheck_file $file) {
-    $errors = [];
-    foreach ($file->get_functions() as $function) {
-        if ($function->phpdocs !== false && !strlen($function->phpdocs->get_description())) {
-            $errors[] = [
-                'line' => $function->phpdocs->get_line_number($file),
-                'object' => $function->name,
-            ];
-        }
-    }
-    return $errors;
-}
-
 /**
  * Checks that all functions have proper arguments in phpdocs
  *