From d472f530acb7e1a86b17b63c8fc02aa89734aa36 Mon Sep 17 00:00:00 2001
From: Juan Leyva <juanleyvadelgado@gmail.com>
Date: Wed, 1 Feb 2017 18:00:05 +0100
Subject: [PATCH] MDL-57846 core_exporter: Allow properties description in
 exporters

---
 lib/classes/external/exporter.php | 20 +++++++++++++++-----
 lib/tests/exporter_test.php       | 15 +++++++++++++++
 2 files changed, 30 insertions(+), 5 deletions(-)

diff --git a/lib/classes/external/exporter.php b/lib/classes/external/exporter.php
index 9539e543a1e..f874ae551eb 100644
--- a/lib/classes/external/exporter.php
+++ b/lib/classes/external/exporter.php
@@ -262,6 +262,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;
@@ -280,6 +283,9 @@ abstract class exporter {
             if (!isset($definition['null'])) {
                 $properties[$property]['null'] = NULL_NOT_ALLOWED;
             }
+            if (!isset($definition['description'])) {
+                $properties[$property]['description'] = $property;
+            }
         }
         return $properties;
     }
@@ -331,7 +337,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
@@ -441,7 +448,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)) {
@@ -504,10 +512,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;
 
@@ -556,7 +565,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)) {
diff --git a/lib/tests/exporter_test.php b/lib/tests/exporter_test.php
index 3c126075d74..afd6a39a7aa 100644
--- a/lib/tests/exporter_test.php
+++ b/lib/tests/exporter_test.php
@@ -153,6 +153,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']);
+    }
 }
 
 /**
@@ -186,6 +199,7 @@ class core_testable_exporter extends \core\external\exporter {
             ),
             'intB' => array(
                 'type' => PARAM_INT,
+                'description' => 'intB description',
             )
         );
     }
@@ -194,6 +208,7 @@ class core_testable_exporter extends \core\external\exporter {
         return array(
             'otherstring' => array(
                 'type' => PARAM_TEXT,
+                'description' => 'otherstring description',
             ),
             'otherstrings' => array(
                 'type' => PARAM_TEXT,