Merge pull request #1702 from ahmadawais/patch-5

danielbachhuber · danielbachhuber · commit 436bfc414ad3 · 2015-10-28T08:55:57.000-07:00
Add Periods to end comments, @params and @returns
diff --git a/lib/endpoints/class-wp-rest-controller.php b/lib/endpoints/class-wp-rest-controller.php
@@ -11,7 +11,7 @@ public function register_routes() {
 	}
 
 	/**
-	 * Get a collection of items
+	 * Get a collection of items.
 	 *
 	 * @param WP_REST_Request $request Full data about the request.
 	 * @return WP_Error|WP_REST_Response
@@ -21,7 +21,7 @@ public function get_items( $request ) {
 	}
 
 	/**
-	 * Get one item from the collection
+	 * Get one item from the collection.
 	 *
 	 * @param WP_REST_Request $request Full data about the request.
 	 * @return WP_Error|WP_REST_Response
@@ -31,7 +31,7 @@ public function get_item( $request ) {
 	}
 
 	/**
-	 * Create one item from the collection
+	 * Create one item from the collection.
 	 *
 	 * @param WP_REST_Request $request Full data about the request.
 	 * @return WP_Error|WP_REST_Response
@@ -41,7 +41,7 @@ public function create_item( $request ) {
 	}
 
 	/**
-	 * Update one item from the collection
+	 * Update one item from the collection.
 	 *
 	 * @param WP_REST_Request $request Full data about the request.
 	 * @return WP_Error|WP_REST_Response
@@ -51,7 +51,7 @@ public function update_item( $request ) {
 	}
 
 	/**
-	 * Delete one item from the collection
+	 * Delete one item from the collection.
 	 *
 	 * @param WP_REST_Request $request Full data about the request.
 	 * @return WP_Error|WP_REST_Response
@@ -61,7 +61,7 @@ public function delete_item( $request ) {
 	}
 
 	/**
-	 * Check if a given request has access to get items
+	 * Check if a given request has access to get items.
 	 *
 	 * @param WP_REST_Request $request Full data about the request.
 	 * @return WP_Error|bool
@@ -71,7 +71,7 @@ public function get_items_permissions_check( $request ) {
 	}
 
 	/**
-	 * Check if a given request has access to get a specific item
+	 * Check if a given request has access to get a specific item.
 	 *
 	 * @param WP_REST_Request $request Full data about the request.
 	 * @return WP_Error|bool
@@ -81,7 +81,7 @@ public function get_item_permissions_check( $request ) {
 	}
 
 	/**
-	 * Check if a given request has access to create items
+	 * Check if a given request has access to create items.
 	 *
 	 * @param WP_REST_Request $request Full data about the request.
 	 * @return WP_Error|bool
@@ -91,7 +91,7 @@ public function create_item_permissions_check( $request ) {
 	}
 
 	/**
-	 * Check if a given request has access to update a specific item
+	 * Check if a given request has access to update a specific item.
 	 *
 	 * @param WP_REST_Request $request Full data about the request.
 	 * @return WP_Error|bool
@@ -101,7 +101,7 @@ public function update_item_permissions_check( $request ) {
 	}
 
 	/**
-	 * Check if a given request has access to delete a specific item
+	 * Check if a given request has access to delete a specific item.
 	 *
 	 * @param WP_REST_Request $request Full data about the request.
 	 * @return WP_Error|bool
@@ -111,17 +111,17 @@ public function delete_item_permissions_check( $request ) {
 	}
 
 	/**
-	 * Prepare the item for create or update operation
+	 * Prepare the item for create or update operation.
 	 *
-	 * @param WP_REST_Request $request Request object
+	 * @param WP_REST_Request $request Request object.
 	 * @return WP_Error|object $prepared_item
 	 */
 	protected function prepare_item_for_database( $request ) {
 		return new WP_Error( 'invalid-method', sprintf( __( "Method '%s' not implemented. Must be over-ridden in subclass." ), __METHOD__ ), array( 'status' => 405 ) );
 	}
 
 	/**
-	 * Prepare the item for the REST response
+	 * Prepare the item for the REST response.
 	 *
 	 * @param mixed $item WordPress representation of the item.
 	 * @param WP_REST_Request $request Request object.
@@ -152,7 +152,7 @@ public function prepare_response_for_collection( $response ) {
 	}
 
 	/**
-	 * Filter a response based on the context defined in the schema
+	 * Filter a response based on the context defined in the schema.
 	 *
 	 * @param array $data
 	 * @param string $context
@@ -186,7 +186,7 @@ public function filter_response_by_context( $data, $context ) {
 	}
 
 	/**
-	 * Get the item's schema, conforming to JSON Schema
+	 * Get the item's schema, conforming to JSON Schema.
 	 *
 	 * @return array
 	 */
@@ -213,7 +213,7 @@ public function get_public_item_schema() {
 	}
 
 	/**
-	 * Get the query params for collections
+	 * Get the query params for collections.
 	 *
 	 * @return array
 	 */
@@ -240,11 +240,11 @@ public function get_collection_params() {
 	}
 
 	/**
-	 * Add the values from additional fields to a data object
+	 * Add the values from additional fields to a data object.
 	 *
 	 * @param array  $object
 	 * @param WP_REST_Request $request
-	 * @return array modified object with additional fields
+	 * @return array modified object with additional fields.
 	 */
 	protected function add_additional_fields_to_object( $object, $request ) {
 
@@ -278,7 +278,7 @@ protected function update_additional_fields_for_object( $object, $request ) {
 				continue;
 			}
 
-			// Don't run the update callbacks if the data wasn't passed in the request
+			// Don't run the update callbacks if the data wasn't passed in the request.
 			if ( ! isset( $request[ $field_name ] ) ) {
 				continue;
 			}
@@ -288,19 +288,19 @@ protected function update_additional_fields_for_object( $object, $request ) {
 	}
 
 	/**
-	 * Add the schema from additional fields to an schema array
+	 * Add the schema from additional fields to an schema array.
 	 *
 	 * The type of object is inferred from the passed schema.
 	 *
-	 * @param array $schema Schema array
+	 * @param array $schema Schema array.
 	 */
 	protected function add_additional_fields_schema( $schema ) {
 		if ( ! $schema || ! isset( $schema['title'] ) ) {
 			return $schema;
 		}
 
 		/**
-		 * Can't use $this->get_object_type otherwise we cause an inf loop
+		 * Can't use $this->get_object_type otherwise we cause an inf loop.
 		 */
 		$object_type = $schema['title'];
 
@@ -318,7 +318,7 @@ protected function add_additional_fields_schema( $schema ) {
 	}
 
 	/**
-	 * Get all the registered additional fields for a given object-type
+	 * Get all the registered additional fields for a given object-type.
 	 *
 	 * @param  string $object_type
 	 * @return array
@@ -497,7 +497,7 @@ public function sanitize_schema_property( $value, $request, $parameter ) {
 
 				case 'email' :
 					// as sanitize_email is very lossy, we just want to
-					// make sure the string is safe
+					// make sure the string is safe.
 					if ( sanitize_email( $value ) ) {
 						return sanitize_email( $value );
 					}

Original file line number	Diff line number	Diff line change
`@@ -11,7 +11,7 @@ public function register_routes() {`
`11`	`11`	`}`
`12`	`12`
`13`	`13`	`/**`
`14`		`- * Get a collection of items`
	`14`	`+ * Get a collection of items.`
`15`	`15`	`*`
`16`	`16`	`* @param WP_REST_Request $request Full data about the request.`
`17`	`17`	`* @return WP_Error\|WP_REST_Response`
`@@ -21,7 +21,7 @@ public function get_items( $request ) {`
`21`	`21`	`}`
`22`	`22`
`23`	`23`	`/**`
`24`		`- * Get one item from the collection`
	`24`	`+ * Get one item from the collection.`
`25`	`25`	`*`
`26`	`26`	`* @param WP_REST_Request $request Full data about the request.`
`27`	`27`	`* @return WP_Error\|WP_REST_Response`
`@@ -31,7 +31,7 @@ public function get_item( $request ) {`
`31`	`31`	`}`
`32`	`32`
`33`	`33`	`/**`
`34`		`- * Create one item from the collection`
	`34`	`+ * Create one item from the collection.`
`35`	`35`	`*`
`36`	`36`	`* @param WP_REST_Request $request Full data about the request.`
`37`	`37`	`* @return WP_Error\|WP_REST_Response`
`@@ -41,7 +41,7 @@ public function create_item( $request ) {`
`41`	`41`	`}`
`42`	`42`
`43`	`43`	`/**`
`44`		`- * Update one item from the collection`
	`44`	`+ * Update one item from the collection.`
`45`	`45`	`*`
`46`	`46`	`* @param WP_REST_Request $request Full data about the request.`
`47`	`47`	`* @return WP_Error\|WP_REST_Response`
`@@ -51,7 +51,7 @@ public function update_item( $request ) {`
`51`	`51`	`}`
`52`	`52`
`53`	`53`	`/**`
`54`		`- * Delete one item from the collection`
	`54`	`+ * Delete one item from the collection.`
`55`	`55`	`*`
`56`	`56`	`* @param WP_REST_Request $request Full data about the request.`
`57`	`57`	`* @return WP_Error\|WP_REST_Response`
`@@ -61,7 +61,7 @@ public function delete_item( $request ) {`
`61`	`61`	`}`
`62`	`62`
`63`	`63`	`/**`
`64`		`- * Check if a given request has access to get items`
	`64`	`+ * Check if a given request has access to get items.`
`65`	`65`	`*`
`66`	`66`	`* @param WP_REST_Request $request Full data about the request.`
`67`	`67`	`* @return WP_Error\|bool`
`@@ -71,7 +71,7 @@ public function get_items_permissions_check( $request ) {`
`71`	`71`	`}`
`72`	`72`
`73`	`73`	`/**`
`74`		`- * Check if a given request has access to get a specific item`
	`74`	`+ * Check if a given request has access to get a specific item.`
`75`	`75`	`*`
`76`	`76`	`* @param WP_REST_Request $request Full data about the request.`
`77`	`77`	`* @return WP_Error\|bool`
`@@ -81,7 +81,7 @@ public function get_item_permissions_check( $request ) {`
`81`	`81`	`}`
`82`	`82`
`83`	`83`	`/**`
`84`		`- * Check if a given request has access to create items`
	`84`	`+ * Check if a given request has access to create items.`
`85`	`85`	`*`
`86`	`86`	`* @param WP_REST_Request $request Full data about the request.`
`87`	`87`	`* @return WP_Error\|bool`
`@@ -91,7 +91,7 @@ public function create_item_permissions_check( $request ) {`
`91`	`91`	`}`
`92`	`92`
`93`	`93`	`/**`
`94`		`- * Check if a given request has access to update a specific item`
	`94`	`+ * Check if a given request has access to update a specific item.`
`95`	`95`	`*`
`96`	`96`	`* @param WP_REST_Request $request Full data about the request.`
`97`	`97`	`* @return WP_Error\|bool`
`@@ -101,7 +101,7 @@ public function update_item_permissions_check( $request ) {`
`101`	`101`	`}`
`102`	`102`
`103`	`103`	`/**`
`104`		`- * Check if a given request has access to delete a specific item`
	`104`	`+ * Check if a given request has access to delete a specific item.`
`105`	`105`	`*`
`106`	`106`	`* @param WP_REST_Request $request Full data about the request.`
`107`	`107`	`* @return WP_Error\|bool`
`@@ -111,17 +111,17 @@ public function delete_item_permissions_check( $request ) {`
`111`	`111`	`}`
`112`	`112`
`113`	`113`	`/**`
`114`		`- * Prepare the item for create or update operation`
	`114`	`+ * Prepare the item for create or update operation.`
`115`	`115`	`*`
`116`		`- * @param WP_REST_Request $request Request object`
	`116`	`+ * @param WP_REST_Request $request Request object.`
`117`	`117`	`* @return WP_Error\|object $prepared_item`
`118`	`118`	`*/`
`119`	`119`	`protected function prepare_item_for_database( $request ) {`
`120`	`120`	`return new WP_Error( 'invalid-method', sprintf( __( "Method '%s' not implemented. Must be over-ridden in subclass." ), __METHOD__ ), array( 'status' => 405 ) );`
`121`	`121`	`}`
`122`	`122`
`123`	`123`	`/**`
`124`		`- * Prepare the item for the REST response`
	`124`	`+ * Prepare the item for the REST response.`
`125`	`125`	`*`
`126`	`126`	`* @param mixed $item WordPress representation of the item.`
`127`	`127`	`* @param WP_REST_Request $request Request object.`
`@@ -152,7 +152,7 @@ public function prepare_response_for_collection( $response ) {`
`152`	`152`	`}`
`153`	`153`
`154`	`154`	`/**`
`155`		`- * Filter a response based on the context defined in the schema`
	`155`	`+ * Filter a response based on the context defined in the schema.`
`156`	`156`	`*`
`157`	`157`	`* @param array $data`
`158`	`158`	`* @param string $context`
`@@ -186,7 +186,7 @@ public function filter_response_by_context( $data, $context ) {`
`186`	`186`	`}`
`187`	`187`
`188`	`188`	`/**`
`189`		`- * Get the item's schema, conforming to JSON Schema`
	`189`	`+ * Get the item's schema, conforming to JSON Schema.`
`190`	`190`	`*`
`191`	`191`	`* @return array`
`192`	`192`	`*/`
`@@ -213,7 +213,7 @@ public function get_public_item_schema() {`
`213`	`213`	`}`
`214`	`214`
`215`	`215`	`/**`
`216`		`- * Get the query params for collections`
	`216`	`+ * Get the query params for collections.`
`217`	`217`	`*`
`218`	`218`	`* @return array`
`219`	`219`	`*/`
`@@ -240,11 +240,11 @@ public function get_collection_params() {`
`240`	`240`	`}`
`241`	`241`
`242`	`242`	`/**`
`243`		`- * Add the values from additional fields to a data object`
	`243`	`+ * Add the values from additional fields to a data object.`
`244`	`244`	`*`
`245`	`245`	`* @param array $object`
`246`	`246`	`* @param WP_REST_Request $request`
`247`		`- * @return array modified object with additional fields`
	`247`	`+ * @return array modified object with additional fields.`
`248`	`248`	`*/`
`249`	`249`	`protected function add_additional_fields_to_object( $object, $request ) {`
`250`	`250`
`@@ -278,7 +278,7 @@ protected function update_additional_fields_for_object( $object, $request ) {`
`278`	`278`	`continue;`
`279`	`279`	`}`
`280`	`280`
`281`		`- // Don't run the update callbacks if the data wasn't passed in the request`
	`281`	`+ // Don't run the update callbacks if the data wasn't passed in the request.`
`282`	`282`	`if ( ! isset( $request[ $field_name ] ) ) {`
`283`	`283`	`continue;`
`284`	`284`	`}`
`@@ -288,19 +288,19 @@ protected function update_additional_fields_for_object( $object, $request ) {`
`288`	`288`	`}`
`289`	`289`
`290`	`290`	`/**`
`291`		`- * Add the schema from additional fields to an schema array`
	`291`	`+ * Add the schema from additional fields to an schema array.`
`292`	`292`	`*`
`293`	`293`	`* The type of object is inferred from the passed schema.`
`294`	`294`	`*`
`295`		`- * @param array $schema Schema array`
	`295`	`+ * @param array $schema Schema array.`
`296`	`296`	`*/`
`297`	`297`	`protected function add_additional_fields_schema( $schema ) {`
`298`	`298`	`if ( ! $schema \|\| ! isset( $schema['title'] ) ) {`
`299`	`299`	`return $schema;`
`300`	`300`	`}`
`301`	`301`
`302`	`302`	`/**`
`303`		`- * Can't use $this->get_object_type otherwise we cause an inf loop`
	`303`	`+ * Can't use $this->get_object_type otherwise we cause an inf loop.`
`304`	`304`	`*/`
`305`	`305`	`$object_type = $schema['title'];`
`306`	`306`
`@@ -318,7 +318,7 @@ protected function add_additional_fields_schema( $schema ) {`
`318`	`318`	`}`
`319`	`319`
`320`	`320`	`/**`
`321`		`- * Get all the registered additional fields for a given object-type`
	`321`	`+ * Get all the registered additional fields for a given object-type.`
`322`	`322`	`*`
`323`	`323`	`* @param string $object_type`
`324`	`324`	`* @return array`
`@@ -497,7 +497,7 @@ public function sanitize_schema_property( $value, $request, $parameter ) {`
`497`	`497`
`498`	`498`	`case 'email' :`
`499`	`499`	`// as sanitize_email is very lossy, we just want to`
`500`		`- // make sure the string is safe`
	`500`	`+ // make sure the string is safe.`
`501`	`501`	`if ( sanitize_email( $value ) ) {`
`502`	`502`	`return sanitize_email( $value );`
`503`	`503`	`}`