From: Andreas Hennings <andreas@dqxtech.net>
Date: Tue, 11 Feb 2014 16:58:22 +0000 (+0100)
Subject: More docblock improvements.
X-Git-Url: https://vcs.fsf.org/?a=commitdiff_plain;h=a3379cc1fcfcbee4f6acca9330d96af6beb2fc55;p=civicrm-core.git

More docblock improvements.
---

diff --git a/CRM/Contribute/Page/ContributionPage.php b/CRM/Contribute/Page/ContributionPage.php
index e71d40e5d5..67b6c8639b 100644
--- a/CRM/Contribute/Page/ContributionPage.php
+++ b/CRM/Contribute/Page/ContributionPage.php
@@ -65,9 +65,9 @@ class CRM_Contribute_Page_ContributionPage extends CRM_Core_Page {
   /**
    * Get the action links for this page.
    *
-   * @return array $_actionLinks
-   *
-   */ function &actionLinks() {
+   * @return array
+   */
+  function &actionLinks() {
     // check if variable _actionsLinks is populated
     if (!isset(self::$_actionLinks)) {
       // helper variable for nicer formatting
@@ -107,8 +107,7 @@ class CRM_Contribute_Page_ContributionPage extends CRM_Core_Page {
   /**
    * Get the configure action links for this page.
    *
-   * @return array $_configureActionLinks
-   *
+   * @return array
    */
   public function &configureActionLinks() {
     // check if variable _actionsLinks is populated
@@ -189,8 +188,7 @@ class CRM_Contribute_Page_ContributionPage extends CRM_Core_Page {
   /**
    * Get the online contribution links.
    *
-   * @return array $_onlineContributionLinks.
-   *
+   * @return array
    */
   public function &onlineContributionLinks() {
     if (!isset(self::$_onlineContributionLinks)) {
@@ -221,8 +219,7 @@ class CRM_Contribute_Page_ContributionPage extends CRM_Core_Page {
   /**
    * Get the contributions links.
    *
-   * @return array $_contributionLinks
-   *
+   * @return array
    */
   public function &contributionLinks() {
     if (!isset(self::$_contributionLinks)) {
@@ -272,7 +269,6 @@ class CRM_Contribute_Page_ContributionPage extends CRM_Core_Page {
    * Finally it calls the parent's run method.
    *
    * @return void
-   *
    */
   public function run() {
     // get the requested action
diff --git a/CRM/Utils/Request.php b/CRM/Utils/Request.php
index 061a0cb547..c872163da2 100644
--- a/CRM/Utils/Request.php
+++ b/CRM/Utils/Request.php
@@ -43,8 +43,7 @@ class CRM_Utils_Request {
    * We only need one instance of this object. So we use the singleton
    * pattern and cache the instance in this variable
    *
-   * @var object
-   * @static
+   * @var self
    */
   static private $_singleton = NULL;
 
@@ -56,15 +55,21 @@ class CRM_Utils_Request {
   /**
    * Retrieve a value from the request (GET/POST/REQUEST)
    *
-   * @param string $name name of the variable to be retrieved
-   * @param string $type  type of the variable (see CRM_Utils_Type for details)
-   * @param object $store session scope where variable is stored
-   * @param bool $abort is this variable required
-   * @param mixed $default default value of the variable if not present
-   * @param string $method where should we look for the variable
+   * @param string $name
+   *   Name of the variable to be retrieved.
+   * @param string $type
+   *   Type of the variable (see CRM_Utils_Type for details).
+   * @param object $store
+   *   Session scope where variable is stored.
+   * @param bool $abort
+   *   TRUE, if the variable is required.
+   * @param mixed $default
+   *   Default value of the variable if not present.
+   * @param string $method
+   *   Where to look for the variable - 'GET', 'POST' or 'REQUEST'.
    *
-   * @return mixed the value of the variable
-   * @static
+   * @return mixed
+   *   The value of the variable
    */
   public static function retrieve($name, $type, &$store = NULL, $abort = FALSE, $default = NULL, $method = 'REQUEST') {
 
diff --git a/CRM/Utils/Type.php b/CRM/Utils/Type.php
index 5f330a05ca..8751442958 100644
--- a/CRM/Utils/Type.php
+++ b/CRM/Utils/Type.php
@@ -66,12 +66,13 @@ class CRM_Utils_Type {
     HUGE      = 45;
 
   /**
-   * Convert Constant Data type to String
+   * Gets the string representation for a data type.
    *
-   * @param  $type       integer datatype
+   * @param int $type
+   *   Integer number identifying the data type.
    *
-   * @return string $string     String datatype respective to integer datatype@access public
-   * @static
+   * @return string
+   *   String identifying the data type, e.g. 'Int' or 'String'.
    */
   public static function typeToString($type) {
     switch ($type) {
@@ -138,14 +139,17 @@ class CRM_Utils_Type {
   }
 
   /**
-   * Verify that a variable is of a given type
+   * Verify that a variable is of a given type, and apply a bit of processing.
    *
-   * @param mixed   $data         The variable
-   * @param string  $type         The type
-   * @param boolean $abort        Should we abort if invalid
+   * @param mixed $data
+   *   The value to be verified/escaped.
+   * @param string $type
+   *   The type to verify against.
+   * @param boolean $abort
+   *   If TRUE, the operation will CRM_Core_Error::fatal() on invalid data.
    *
-   * @return mixed                The data, escaped if necessary
-   * @static
+   * @return mixed
+   *   The data, escaped if necessary.
    */
   public static function escape($data, $type, $abort = TRUE) {
     switch ($type) {
@@ -254,13 +258,17 @@ class CRM_Utils_Type {
   /**
    * Verify that a variable is of a given type
    *
-   * @param mixed   $data         The variable
-   * @param string  $type         The type
-   * @param boolean $abort        Should we abort if invalid
-   * @name string   $name    The name of the attribute
+   * @param mixed $data
+   *   The value to validate.
+   * @param string $type
+   *   The type to validate against.
+   * @param boolean $abort
+   *   If TRUE, the operation will CRM_Core_Error::fatal() on invalid data.
+   * @name string $name
+   *   The name of the attribute
    *
-   * @return mixed                The data, escaped if necessary
-   * @static
+   * @return mixed
+   *   The data, escaped if necessary
    */
   public static function validate($data, $type, $abort = TRUE, $name = 'One of parameters ') {
     switch ($type) {