From 3337a7aff02b9e6f96ab860225f3b38cecc81b9f Mon Sep 17 00:00:00 2001 From: Katherine Senzee Date: Thu, 5 Apr 2012 11:16:12 -0400 Subject: [PATCH] Issue #1516472: Add API documentation for configuration system. --- core/includes/config.inc | 22 ++++++----- core/lib/Drupal/Core/Config/ConfigException.php | 2 +- .../Core/Config/ConfigFileStorageException.php | 2 +- .../Core/Config/ConfigFileStorageReadException.php | 2 +- .../Config/ConfigFileStorageSignatureException.php | 2 +- core/lib/Drupal/Core/Config/DrupalConfig.php | 37 +++++++++++-------- .../Core/Config/DrupalConfigVerifiedStorage.php | 11 ++++-- .../DrupalConfigVerifiedStorageInterface.php | 9 ++++- .../Core/Config/DrupalVerifiedStorageSQL.php | 2 +- core/lib/Drupal/Core/Config/SignedFileStorage.php | 18 +++++----- 10 files changed, 61 insertions(+), 46 deletions(-) diff --git a/core/includes/config.inc b/core/includes/config.inc index 8c2772b..c1aad47 100644 --- a/core/includes/config.inc +++ b/core/includes/config.inc @@ -96,13 +96,15 @@ function config_sign_data($data) { } /** - * @todo + * Gets configuration key names starting with a given prefix. * * @param $prefix - * @todo + * A prefix representing the key names to be returned, such as + * 'entity.node.'. * - * @return - * @todo + * @return array + * An array of all key names beginning with the specified prefix, such as + * 'entity.node.page' and 'entity.node.article'. */ function config_get_verified_storage_names_with_prefix($prefix = '') { return DrupalVerifiedStorageSQL::getNamesWithPrefix($prefix); @@ -159,11 +161,11 @@ function config_decode($data) { /** * Standardizes SimpleXML object output into simple arrays for easier use. * - * @param $xmlObject - * A valid XML string. + * @param string $data + * A valid XML string that can be converted into a SimpleXML object. * * @return - * An array representation of A SimpleXML object. + * An array representation of a SimpleXML object. */ function config_xml_to_array($data) { $out = array(); @@ -191,7 +193,7 @@ function config_xml_to_array($data) { * Encodes an array into the native configuration format. * * @param $data - * An associative array or an object + * An associative array or an object. * * @return * A representation of this array or object in the native configuration @@ -215,10 +217,10 @@ function config_encode($data) { } /** - * Encodes an array into XML + * Encodes an array into XML. * * @param $data - * An associative array or an object + * An associative array or an object. * * @return * A representation of this array or object in the native configuration diff --git a/core/lib/Drupal/Core/Config/ConfigException.php b/core/lib/Drupal/Core/Config/ConfigException.php index c60a449..52564c8 100644 --- a/core/lib/Drupal/Core/Config/ConfigException.php +++ b/core/lib/Drupal/Core/Config/ConfigException.php @@ -3,6 +3,6 @@ namespace Drupal\Core\Config; /** - * @todo + * Defines an exception thrown within the configuration system. */ class ConfigException extends \Exception {} diff --git a/core/lib/Drupal/Core/Config/ConfigFileStorageException.php b/core/lib/Drupal/Core/Config/ConfigFileStorageException.php index ce7fb30..4dfbba5 100644 --- a/core/lib/Drupal/Core/Config/ConfigFileStorageException.php +++ b/core/lib/Drupal/Core/Config/ConfigFileStorageException.php @@ -5,6 +5,6 @@ namespace Drupal\Core\Config; use Drupal\Core\Config\ConfigException; /** - * @todo + * Defines an exception thrown in the case of a file storage error. */ class ConfigFileStorageException extends ConfigException {} diff --git a/core/lib/Drupal/Core/Config/ConfigFileStorageReadException.php b/core/lib/Drupal/Core/Config/ConfigFileStorageReadException.php index a3ac95c..5501fc3 100644 --- a/core/lib/Drupal/Core/Config/ConfigFileStorageReadException.php +++ b/core/lib/Drupal/Core/Config/ConfigFileStorageReadException.php @@ -5,6 +5,6 @@ namespace Drupal\Core\Config; use Drupal\Core\Config\ConfigFileStorageException; /** - * @todo + * Defines an exception thrown when there is an error reading from file storage. */ class ConfigFileStorageReadException extends ConfigFileStorageException {} diff --git a/core/lib/Drupal/Core/Config/ConfigFileStorageSignatureException.php b/core/lib/Drupal/Core/Config/ConfigFileStorageSignatureException.php index 65c5c59..caff6a4 100644 --- a/core/lib/Drupal/Core/Config/ConfigFileStorageSignatureException.php +++ b/core/lib/Drupal/Core/Config/ConfigFileStorageSignatureException.php @@ -5,6 +5,6 @@ namespace Drupal\Core\Config; use Drupal\Core\Config\ConfigFileStorageException; /** - * @todo + * Defines an exception thrown in the case of a file storage signature error. */ class ConfigFileStorageSignatureException extends ConfigFileStorageException {} diff --git a/core/lib/Drupal/Core/Config/DrupalConfig.php b/core/lib/Drupal/Core/Config/DrupalConfig.php index 9fc33aa..aeeeccb 100644 --- a/core/lib/Drupal/Core/Config/DrupalConfig.php +++ b/core/lib/Drupal/Core/Config/DrupalConfig.php @@ -52,10 +52,10 @@ class DrupalConfig { * Checks whether a particular value is overridden. * * @param $key - * @todo + * A key within the configuration object. * - * @return - * @todo + * @return bool + * TRUE if the value is overridden, FALSE otherwise. */ public function isOverridden($key) { return isset($this->_overrides[$key]); @@ -65,20 +65,20 @@ class DrupalConfig { * Gets data from this config object. * * @param $key - * A string that maps to a key within the configuration data. - * For instance in the following XML: + * A string that maps to a key within the configuration data. Example: * @code * * baz * * @endcode - * A key of 'foo.bar' would return the string 'baz'. However, a key of 'foo' - * would return array('bar' => 'baz'). - * If no key is specified, then the entire data array is returned. + * In the configuration object represented by the above XML, a key of + * 'foo.bar' would return the string 'baz'. However, a key of 'foo' would + * return array('bar' => 'baz'). If no key is specified, then the entire + * data array is returned. * * The configuration system does not retain data types. Every saved value is - * casted to a string. In most cases this is not an issue; however, it can - * cause issues with Booleans, which are casted to "1" (TRUE) or "0" (FALSE). + * cast to a string. In most cases this is not an issue; however, it can + * cause issues with Booleans, which are cast to "1" (TRUE) or "0" (FALSE). * In particular, code relying on === or !== will no longer function properly. * * @see http://php.net/manual/language.operators.comparison.php. @@ -117,9 +117,13 @@ class DrupalConfig { * Sets value in this config object. * * @param $key - * @todo + * A string that maps to a value within the configuration data object. + * * @param $value - * @todo + * The value to set within the configuration data object. May be an array + * or a scalar; if scalar, will be cast to a string. + * + * @see DrupalConfig::castValue() */ public function set($key, $value) { // Remove all non-alphanumeric characters from the key. @@ -146,16 +150,17 @@ class DrupalConfig { * Casts a saved value to a string. * * The configuration system only saves strings or arrays. Any scalar - * non-string value is cast to a string. The one exception is boolean FALSE + * non-string value is cast to a string. The one exception is boolean FALSE, * which would normally become '' when cast to a string, but is manually * cast to '0' here for convenience and consistency. * - * Any non-scalar value that is not an array (aka objects) gets cast - * to an array. + * Any non-scalar value that is not an array (such as an object) gets cast to + * an array. * * @param $value * A value being saved into the configuration system. - * @param $value + * + * @return * The value cast to a string or array. */ public function castValue($value) { diff --git a/core/lib/Drupal/Core/Config/DrupalConfigVerifiedStorage.php b/core/lib/Drupal/Core/Config/DrupalConfigVerifiedStorage.php index 267c834..429cce5 100644 --- a/core/lib/Drupal/Core/Config/DrupalConfigVerifiedStorage.php +++ b/core/lib/Drupal/Core/Config/DrupalConfigVerifiedStorage.php @@ -6,7 +6,7 @@ use Drupal\Core\Config\DrupalConfigVerifiedStorageInterface; use Drupal\Core\Config\SignedFileStorage; /** - * @todo + * Base class for verified configuration storage implementations. */ abstract class DrupalConfigVerifiedStorage implements DrupalConfigVerifiedStorageInterface { @@ -61,12 +61,15 @@ abstract class DrupalConfigVerifiedStorage implements DrupalConfigVerifiedStorag } /** - * @todo + * Returns the contents of the configuration file. * - * @return - * @todo + * @return string + * The contents of the configuration file. + * + * @throws Exception */ public function readFromFile() { + // @todo: Catch the exception thrown from SignedFileStorage::read(). return $this->signedFileStorage()->read($this->name); } diff --git a/core/lib/Drupal/Core/Config/DrupalConfigVerifiedStorageInterface.php b/core/lib/Drupal/Core/Config/DrupalConfigVerifiedStorageInterface.php index 47a5ddb..29db8fd 100644 --- a/core/lib/Drupal/Core/Config/DrupalConfigVerifiedStorageInterface.php +++ b/core/lib/Drupal/Core/Config/DrupalConfigVerifiedStorageInterface.php @@ -75,10 +75,15 @@ interface DrupalConfigVerifiedStorageInterface { function writeToFile($data); /** - * Gets names starting with this prefix. + * Gets configuration key names starting with a given prefix. * * @param $prefix - * @todo + * A prefix representing the key names to be returned. + * + * @return array + * An array of all key names beginning with the specified prefix. + * + * @see config_get_verified_storage_names_with_prefix */ static function getNamesWithPrefix($prefix); diff --git a/core/lib/Drupal/Core/Config/DrupalVerifiedStorageSQL.php b/core/lib/Drupal/Core/Config/DrupalVerifiedStorageSQL.php index 97d499a..13d09bd 100644 --- a/core/lib/Drupal/Core/Config/DrupalVerifiedStorageSQL.php +++ b/core/lib/Drupal/Core/Config/DrupalVerifiedStorageSQL.php @@ -36,7 +36,7 @@ class DrupalVerifiedStorageSQL extends DrupalConfigVerifiedStorage { } /** - * @todo + * Deletes all configuration data for this object from the active store. */ public function deleteFromActive() { db_delete('config') diff --git a/core/lib/Drupal/Core/Config/SignedFileStorage.php b/core/lib/Drupal/Core/Config/SignedFileStorage.php index c669029..24c7cce 100644 --- a/core/lib/Drupal/Core/Config/SignedFileStorage.php +++ b/core/lib/Drupal/Core/Config/SignedFileStorage.php @@ -27,8 +27,7 @@ class SignedFileStorage { * @return * An array with "signature" and "data" keys. * - * @throws - * Exception + * @throws Exception */ protected function readWithSignature() { $content = file_get_contents($this->getFilePath()); @@ -45,8 +44,8 @@ class SignedFileStorage { /** * Checks whether the XML configuration file already exists on disk. * - * @return - * @todo + * @return bool + * TRUE if the file exists on disk, FALSE otherwise. */ protected function exists() { return file_exists($this->getFilePath()); @@ -55,8 +54,8 @@ class SignedFileStorage { /** * Returns the path to the XML configuration file. * - * @return - * @todo + * @return string + * The path to the XML configuration file on disk. */ public function getFilePath() { return config_get_config_directory() . '/' . $this->name . '.xml'; @@ -103,8 +102,7 @@ class SignedFileStorage { * @param $data * The data to be written to the file. * - * @throws - * Exception + * @throws Exception */ public function write($data) { $signature = config_sign_data($data); @@ -120,7 +118,9 @@ class SignedFileStorage { * Returns the contents of the configuration file. * * @return - * @todo + * The contents of the verified file. + * + * @throws Exception */ public function read() { if ($this->exists()) { -- 1.7.5.4