Merge branch 'MDL-57846-master' of git://github.com/jleyva/moodle
authorEloy Lafuente (stronk7) <stronk7@moodle.org>
Mon, 6 Feb 2017 23:12:30 +0000 (00:12 +0100)
committerEloy Lafuente (stronk7) <stronk7@moodle.org>
Mon, 6 Feb 2017 23:12:30 +0000 (00:12 +0100)
lib/classes/external/exporter.php
lib/tests/exporter_test.php

index a80d6a4..dcfeb4e 100644 (file)
@@ -266,6 +266,9 @@ abstract class exporter {
             if (!isset($definition['null'])) {
                 $customprops[$property]['null'] = NULL_NOT_ALLOWED;
             }
+            if (!isset($definition['description'])) {
+                $customprops[$property]['description'] = $property;
+            }
         }
         $properties += $customprops;
         return $properties;
@@ -284,6 +287,9 @@ abstract class exporter {
             if (!isset($definition['null'])) {
                 $properties[$property]['null'] = NULL_NOT_ALLOWED;
             }
+            if (!isset($definition['description'])) {
+                $properties[$property]['description'] = $property;
+            }
         }
         return $properties;
     }
@@ -335,7 +341,8 @@ abstract class exporter {
      * Return the list of properties.
      *
      * The format of the array returned by this method has to match the structure
-     * defined in {@link \core\persistent::define_properties()}.
+     * defined in {@link \core\persistent::define_properties()}. Howewer you can
+     * add a new attribute "description" to describe the parameter for documenting the API.
      *
      * Note that the type PARAM_TEXT should ONLY be used for strings which need to
      * go through filters (multilang, etc...) and do not have a FORMAT_* associated
@@ -445,7 +452,8 @@ abstract class exporter {
                 $returns += self::get_context_structure();
 
             } else {
-                $returns[$property] = new external_value($definition['type'], $property, $required, $default, $definition['null']);
+                $returns[$property] = new external_value($definition['type'], $definition['description'], $required, $default,
+                    $definition['null']);
 
                 // Magically treat the format properties.
                 if ($formatproperty = self::get_format_field($properties, $property)) {
@@ -508,10 +516,11 @@ abstract class exporter {
                     // PARAM_TEXT always becomes PARAM_RAW because filters may be applied.
                     $type = PARAM_RAW;
                 }
-                $thisvalue = new external_value($type, $property, $proprequired, $propdefault, $definition['null']);
+                $thisvalue = new external_value($type, $definition['description'], $proprequired, $propdefault, $definition['null']);
             }
             if (!empty($definition['multiple'])) {
-                $returns[$property] = new external_multiple_structure($thisvalue, '', $proprequired, $propdefault);
+                $returns[$property] = new external_multiple_structure($thisvalue, $definition['description'], $proprequired,
+                    $propdefault);
             } else {
                 $returns[$property] = $thisvalue;
 
@@ -560,7 +569,8 @@ abstract class exporter {
                 $returns += self::get_context_structure();
 
             } else {
-                $returns[$property] = new external_value($definition['type'], $property, $required, $default, $definition['null']);
+                $returns[$property] = new external_value($definition['type'], $definition['description'], $required, $default,
+                    $definition['null']);
 
                 // Magically treat the format properties.
                 if ($formatproperty = self::get_format_field($properties, $property)) {
index 6d5b775..f456628 100644 (file)
@@ -167,6 +167,19 @@ class core_exporter_testcase extends advanced_testcase {
         $this->assertEquals($expected, $result->stringA);
         $this->assertEquals(FORMAT_HTML, $result->stringAformat);
     }
+
+    public function test_properties_description() {
+        $properties = core_testable_exporter::read_properties_definition();
+        // Properties default description.
+        $this->assertEquals('stringA', $properties['stringA']['description']);
+        $this->assertEquals('stringAformat', $properties['stringAformat']['description']);
+        // Properties custom description.
+        $this->assertEquals('intB description', $properties['intB']['description']);
+        // Other properties custom description.
+        $this->assertEquals('otherstring description', $properties['otherstring']['description']);
+        // Other properties default description.
+        $this->assertEquals('otherstrings', $properties['otherstrings']['description']);
+    }
 }
 
 /**
@@ -201,6 +214,7 @@ class core_testable_exporter extends \core\external\exporter {
             ),
             'intB' => array(
                 'type' => PARAM_INT,
+                'description' => 'intB description',
             )
         );
     }
@@ -209,6 +223,7 @@ class core_testable_exporter extends \core\external\exporter {
         return array(
             'otherstring' => array(
                 'type' => PARAM_TEXT,
+                'description' => 'otherstring description',
             ),
             'otherstrings' => array(
                 'type' => PARAM_TEXT,