TemplateDataBlob: Add comments referencing parts of the spec

Also moved 'inherit' up to make the code easier to follow.

Change-Id: I0059236924c5b49bff71a745b9895651c4eb6d0b

TemplateDataBlob.php

@@ -62,14 +62,7 @@ class TemplateDataBlob {
 			}
 		}
 
-		if ( !isset( $data->params ) ) {
+		// Root.description
-			return Status::newFatal( 'templatedata-invalid-missing', 'params', 'object' );
-		}
-
-		if ( !is_object( $data->params ) ) {
-			return Status::newFatal( 'templatedata-invalid-type', 'params', 'object' );
-		}
-
 		if ( isset( $data->description ) ) {
 			if ( !is_object( $data->description ) && !is_string( $data->description ) ) {
 				return Status::newFatal( 'templatedata-invalid-type', 'description', 'string|object' );
@@ -79,6 +72,15 @@ class TemplateDataBlob {
 			$data->description = self::normaliseInterfaceText( '' );
 		}
 
+		// Root.params
+		if ( !isset( $data->params ) ) {
+			return Status::newFatal( 'templatedata-invalid-missing', 'params', 'object' );
+		}
+
+		if ( !is_object( $data->params ) ) {
+			return Status::newFatal( 'templatedata-invalid-type', 'params', 'object' );
+		}
+
 		foreach ( $data->params as $paramName => $paramObj ) {
 			if ( !is_object( $paramObj ) ) {
 				return Status::newFatal( 'templatedata-invalid-type', 'params.' . $paramName, 'object' );
@@ -97,6 +99,21 @@ class TemplateDataBlob {
 				}
 			}
 
+			// Param.inherits
+			// TODO: Implementation specifies we use inherit (target references origin), instead
+			// of clone (origin lists targets).
+			if ( isset( $paramObj->clones ) ) {
+				if ( !is_array( $paramObj->clones ) ) {
+					// TODO: Validate the array values.
+					return Status::newFatal( 'templatedata-invalid-type', 'params.' . $paramName . '.clones', 'array' );
+				}
+			} else {
+				$paramObj->clones = array();
+			}
+
+			// TODO: Param.label
+
+			// Param.required
 			if ( isset( $paramObj->required ) ) {
 				if ( !is_bool( $paramObj->required ) ) {
 					return Status::newFatal( 'templatedata-invalid-type', 'params.' . $paramName . '.required', 'boolean' );
@@ -105,6 +122,7 @@ class TemplateDataBlob {
 				$paramObj->required = false;
 			}
 
+			// Param.description
 			if ( isset( $paramObj->description ) ) {
 				if ( !is_object( $paramObj->description ) && !is_string( $paramObj->description ) ) {
 					// TODO: Also validate that if it is an object, the keys are valid lang codes
@@ -116,6 +134,7 @@ class TemplateDataBlob {
 				$paramObj->description = self::normaliseInterfaceText( '' );
 			}
 
+			// Param.deprecated
 			if ( isset( $paramObj->deprecated ) ) {
 				if ( $paramObj->deprecated !== false && !is_string( $paramObj->deprecated ) ) {
 					return Status::newFatal( 'templatedata-invalid-type', 'params.' . $paramName . '.deprecated', 'boolean|string' );
@@ -124,6 +143,7 @@ class TemplateDataBlob {
 				$paramObj->deprecated = false;
 			}
 
+			// Param.aliases
 			if ( isset( $paramObj->aliases ) ) {
 				if ( !is_array( $paramObj->aliases ) ) {
 					// TODO: Validate the array values.
@@ -133,15 +153,7 @@ class TemplateDataBlob {
 				$paramObj->aliases = array();
 			}
 
-			if ( isset( $paramObj->clones ) ) {
+			// Param.default
-				if ( !is_array( $paramObj->clones ) ) {
-					// TODO: Validate the array values.
-					return Status::newFatal( 'templatedata-invalid-type', 'params.' . $paramName . '.clones', 'array' );
-				}
-			} else {
-				$paramObj->clones = array();
-			}
-
 			if ( isset( $paramObj->default ) ) {
 				if ( !is_string( $paramObj->default ) ) {
 					return Status::newFatal( 'templatedata-invalid-type', 'params.' . $paramName . '.default', 'string' );
@@ -149,8 +161,12 @@ class TemplateDataBlob {
 			} else {
 				$paramObj->default = '';
 			}
+
+			// TODO: Param.type
 		}
 
+		// TODO: Root.sets
+
 		return Status::newGood();
 	}
 

spec.templatedata.json

@@ -14,6 +14,9 @@
 	 Keyed by an internal id, contains #Set objects.
 
 @structure {Object} Param
+	@property {string} [inherits] Key to another object in `Root.params`.
+	 The current Param object will inherit from that one, with local properties
+	 overriding the inherited ones.
 	@property {InterfaceText} [label] Defaults to key of object in `Root.params`.
 	@property {boolean} [required=false]
 	@property {InterfaceText} [description]
@@ -24,9 +27,6 @@
 	 (not in addition to) the primary name. Aliases are not documented in a
 	 separate Param object. If they need more information, they should be in their
 	 own property marked "deprecated".
-	@property {string} [inherits] Key to another object in `Root.params`.
-	 The current Param object will inherit from that one, with local properties
-	 overriding the inherited ones.
 	@property {string} [default] The default value or description thereof.
 	@property {Type} [type] The type of the expected parameter value.