Changeset 44497 for trunk/tests/phpunit/includes/factory/class-wp-unittest-factory-for-thing.php

Timestamp:

01/09/2019 05:43:14 AM (6 years ago)

Author:

pento

Message:

Docs: Add docblocks for the PHPUnit factory objects.

Props andizer.
Fixes #44521.

File:

• trunk/tests/phpunit/includes/factory/class-wp-unittest-factory-for-thing.php (modified) (6 diffs)

trunk/tests/phpunit/includes/factory/class-wp-unittest-factory-for-thing.php

@@ -22 +22 @@
     }
 
+    /**
+     * Creates an object.
+     *
+     * @param array $args The arguments.
+     *
+     * @return mixed The result. Can be anything.
+     */
     abstract function create_object( $args );
+
+    /**
+     * Updates an existing object.
+     *
+     * @param int   $object The object id.
+     * @param array $fields The values to update.
+     *
+     * @return mixed The result. Can be anything.
+     */
     abstract function update_object( $object, $fields );
 
+    /**
+     * Creates an object.
+     *
+     * @param array $args                   Optional. The arguments for the object to create. Default is empty array.
+     * @param null  $generation_definitions Optional. The default values for the object. Default is null.
+     *
+     * @return mixed The result. Can be anything.
+     */
     function create( $args = array(), $generation_definitions = null ) {
         if ( is_null( $generation_definitions ) ) {
@@ -46 +70 @@
     }
 
+    /**
+     * Creates an object and returns its object.
+     *
+     * @param array $args                   Optional. The arguments for the object to create. Default is empty array.
+     * @param null  $generation_definitions Optional. The default values for the object. Default is null.
+     *
+     * @return mixed The created object. Can be anything.
+     */
     function create_and_get( $args = array(), $generation_definitions = null ) {
         $object_id = $this->create( $args, $generation_definitions );
@@ -51 +83 @@
     }
 
+    /**
+     * Retrieves an object by ID.
+     *
+     * @param int $object_id The object id.
+     *
+     * @return mixed The object. Can be anything.
+     */
     abstract function get_object_by_id( $object_id );
 
+    /**
+     * Creates multiple objects.
+     *
+     * @param int   $count                  Amount of objects to create.
+     * @param array $args                   Optional. The arguments for the object to create. Default is empty array.
+     * @param null  $generation_definitions Optional. The default values for the object. Default is null.
+     *
+     * @return array
+     */
     function create_many( $count, $args = array(), $generation_definitions = null ) {
         $results = array();
@@ -61 +109 @@
     }
 
+    /**
+     * Combines the given argument with the generation_definitions (defaults) and applies
+     * possibly set callbacks on it.
+     *
+     * @param array       $args                   Optional. The arguments to combine with defaults. Default is empty array.
+     * @param array|null  $generation_definitions Optional. The defaults. Default is null.
+     * @param array|null  $callbacks              Optional. Array with callbacks to apply on the fields. Default is null.
+     *
+     * @return array|WP_Error Combined array on success. WP_Error when default value is incorrent.
+     */
     function generate_args( $args = array(), $generation_definitions = null, &$callbacks = null ) {
         $callbacks = array();
@@ -89 +147 @@
     }
 
+
+    /**
+     * Applies the callbacks on the created object.
+     *
+     * @param WP_UnitTest_Factory_Callback_After_Create[] $callbacks Array with callback functions.
+     * @param mixed                                       $created   The object to apply callbacks for.
+     *
+     * @return array The altered fields.
+     */
     function apply_callbacks( $callbacks, $created ) {
         $updated_fields = array();
+
         foreach ( $callbacks as $field_name => $generator ) {
             $updated_fields[ $field_name ] = $generator->call( $created );
@@ -97 +165 @@
     }
 
+    /**
+     * Instantiates a callback objects for the given function name.
+     *
+     * @param string $function The callback function.
+     *
+     * @return WP_UnitTest_Factory_Callback_After_Create
+     */
     function callback( $function ) {
         return new WP_UnitTest_Factory_Callback_After_Create( $function );
     }
 
+    /**
+     * Adds slashes to the given value.
+     *
+     * @param array|object|string|mixed $value The value to add slashes to.
+     *
+     * @return array|string The value with the possibly applied slashes.
+     */
     function addslashes_deep( $value ) {
         if ( is_array( $value ) ) {