From 2a7afea8e40200bb719b2ebd89b68bd041ec0aac Mon Sep 17 00:00:00 2001 From: mmorris Date: Mon, 29 Jun 2015 14:12:48 -0400 Subject: [PATCH] API documentation added. --- core/core.api.php | 56 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 56 insertions(+) diff --git a/core/core.api.php b/core/core.api.php index a8b13ca..a4c45e5 100644 --- a/core/core.api.php +++ b/core/core.api.php @@ -57,6 +57,7 @@ * - @link queue Queue API @endlink * - @link typed_data Typed Data @endlink * - @link testing Automated tests @endlink + * - @link assertions Assert Statements @endlink * - @link third_party Integrating third-party applications @endlink * * @section more_info Further information @@ -983,6 +984,61 @@ */ /** + * @defgroup assertions Assert Statements + * @{ + * Use of the Assert statement in Drupal. + * + * An assertion is a special type of error function that is used during the + * development of code. The Drupal project has adopted them to help monitor + * interactions between core code and third party modules. + * + * Unlike errors or exceptions, assertions can be disabled, and in this state + * they are ignored by PHP. For this reason they can't be used as control + * structures in any way. They are used to document and check conditions the + * progammer expects to be outright impossible if there are no errors in the + * code and in the configuration. Keep this in mind when you come across an + * assert statement in code - whatever the condition that is being checked + * for, it is one the author of that assertion believed was completely + * impossible so if it's happening there's a bug elsewhere in the code. + * + * Assert statements are most commonly used to enforce API expectations in a + * manner similar to type hinting, but they can enforce more complicated data + * structures, such as verifying an array contains only strings. Until PHP 7 + * becomes the baseline for Drupal they provide a means to verify the + * returns of functions. They can make other checks as well, such as checking + * to see if a dependency has been set on an object before calling it. + * + * These checks are unnecessary once development concludes, and collectively + * they hurt performance significantly. Assert is therefore used in preference + * to exception throwing since assert statements can be disabled. + * + * Assert statements are not a replacement for unit tests - they are a + * supplement. Unit tests excel at testing code units both individually and + * in small groups. Functional tests run the system through its paces in known + * scenarios. Neither can handle the unknown - this is where the assert + * statement comes into its own. It can test the validity of code that hasn't + * been written yet. They are part of a part of a methodology known as design + * by contract. + * + * @section assert_use Using the assert statement + * The @link http://php.net/manual/en/function.assert.php assert @endlink + * statement is part of the PHP language. The language allows you to pass any + * value you want to the statement as its first argument, but you are strongly + * encouraged to only use strings to minimize overhead when assertion checking + * is turned off. + * + * Keep in mind that strings passed to assert will be evaluated as per the + * eval() statement. Use single quotes only to insure any contained variables + * are not parsed when the error is displayed. + * + * If you have activated the settings.local.php file then assertions will be + * turned on while your module or theme is running. + * + * @see https://www.drupal.org/node/2492225 + * @} + */ + +/** * @defgroup info_types Information types * @{ * Types of information in Drupal. -- 1.8.4.2