fix codesniffer issues and improve php comments

Author: Menrath

classes/snippets.php

@@ -96,6 +96,7 @@ public static function get_snippet_scss($path, $source) {
      * Get a snippet defined in the code based on path.
      *
      * @param string $path
+     * @param string $source
      *
      * @return mixed
      */
@@ -105,16 +106,20 @@ public static function get_snippet_meta($path, $source) {
         // Get the snippets file, based on the source.
         $file = self::get_snippet_file($path, $source);
 
+        // If the file does not exist or is not readable, we can not proceed.
         if (is_null($file)) {
-            return;
+            return null;
         }
 
+        // Extract the meta from the SCSS files top level multiline comment in WordPress style.
         $headers = self::get_snippet_meta_from_file($file);
 
+        // The title is the only required meta-key that actually must be set.
         if (!array_key_exists('Snippet Title', $headers)) {
             return null;
         }
 
+        // Create an object containing the information.
         $snippet = new \stdClass();
         $snippet->title = $headers['Snippet Title'];
         $snippet->description = $headers['Description'];
@@ -126,18 +131,23 @@ public static function get_snippet_meta($path, $source) {
     }
 
     /**
-     * Compose snippets file data to record.
+     * Combine snippets meta data from the snippets file with the database record.
+     *
+     * This is currently used for create the view for the settings table.
      *
-     * @param mixed $data
+     * @param moodle_recordset $snippetrecordset
      *
      * @return array
      */
     public static function compose_snippets_data($snippetrecordset) {
         $snippets = [];
 
         foreach ($snippetrecordset as $snippetrecord) {
+            // Get the meta information from the SCSS files top multiline comment.
             $snippet = self::get_snippet_meta($snippetrecord->path, $snippetrecord->source);
+            // If snippets meta is not found, it will no be added to the returned snippet array.
             if ($snippet) {
+                // Merge the two objects.
                 $snippets[] = (object) array_merge((array) $snippetrecord, (array) $snippet);
             }
         }