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)
1  2 
lib/classes/external/exporter.php
lib/tests/exporter_test.php

@@@ -96,11 -96,7 +96,11 @@@ abstract class exporter 
                  }
  
              } else {
 -                if (array_key_exists($key, $related) && $related[$key] instanceof $classname) {
 +                $scalartypes = ['string', 'int', 'bool', 'float'];
 +                $scalarcheck = 'is_' . $classname;
 +                if (array_key_exists($key, $related) &&
 +                        ((in_array($classname, $scalartypes) && $scalarcheck($related[$key])) ||
 +                        ($related[$key] instanceof $classname))) {
                      $this->related[$key] = $related[$key];
                  } else {
                      throw new coding_exception($missingdataerr . $key . ' => ' . $classname);
              if (!isset($definition['null'])) {
                  $customprops[$property]['null'] = NULL_NOT_ALLOWED;
              }
+             if (!isset($definition['description'])) {
+                 $customprops[$property]['description'] = $property;
+             }
          }
          $properties += $customprops;
          return $properties;
              if (!isset($definition['null'])) {
                  $properties[$property]['null'] = NULL_NOT_ALLOWED;
              }
+             if (!isset($definition['description'])) {
+                 $properties[$property]['description'] = $property;
+             }
          }
          return $properties;
      }
       * 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
                  $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)) {
                      // 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;
  
                  $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)) {
@@@ -41,22 -41,8 +41,22 @@@ class core_exporter_testcase extends ad
  
      public function setUp() {
          $s = new stdClass();
 -        $this->validrelated = array('simplestdClass' => $s, 'arrayofstdClass' => array($s, $s), 'context' => null);
 -        $this->invalidrelated = array('simplestdClass' => 'a string', 'arrayofstdClass' => 5, 'context' => null);
 +        $this->validrelated = array(
 +            'simplestdClass' => $s,
 +            'arrayofstdClass' => array($s, $s),
 +            'context' => null,
 +            'aint' => 5,
 +            'astring' => 'valid string',
 +            'abool' => false
 +        );
 +        $this->invalidrelated = array(
 +            'simplestdClass' => 'a string',
 +            'arrayofstdClass' => 5,
 +            'context' => null,
 +            'aint' => false,
 +            'astring' => 4,
 +            'abool' => 'not a boolean'
 +        );
  
          $this->validdata = array('stringA' => 'A string', 'stringAformat' => FORMAT_HTML, 'intB' => 4);
  
          $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']);
+     }
  }
  
  /**
@@@ -180,8 -179,7 +193,8 @@@ class core_testable_exporter extends \c
  
      protected static function define_related() {
          // We cache the context so it does not need to be retrieved from the course.
 -        return array('simplestdClass' => 'stdClass', 'arrayofstdClass' => 'stdClass[]', 'context' => 'context?');
 +        return array('simplestdClass' => 'stdClass', 'arrayofstdClass' => 'stdClass[]', 'context' => 'context?',
 +            'astring' => 'string', 'abool' => 'bool', 'aint' => 'int');
      }
  
      protected function get_other_values(renderer_base $output) {
              ),
              'intB' => array(
                  'type' => PARAM_INT,
+                 'description' => 'intB description',
              )
          );
      }
          return array(
              'otherstring' => array(
                  'type' => PARAM_TEXT,
+                 'description' => 'otherstring description',
              ),
              'otherstrings' => array(
                  'type' => PARAM_TEXT,