From 7cdf0f5b2f88fda51b25b1d21d0f83dd39e9a1d5 Mon Sep 17 00:00:00 2001
From: Andreas Hennings <andreas@dqxtech.net>
Date: Tue, 11 Feb 2014 20:30:20 +0100
Subject: [PATCH] Docblock improvements

---
 CRM/Utils/System/Base.php | 64 ++++++++++++++++++++++-----------------
 1 file changed, 37 insertions(+), 27 deletions(-)

diff --git a/CRM/Utils/System/Base.php b/CRM/Utils/System/Base.php
index 4ed43e16b9..8dbb701109 100644
--- a/CRM/Utils/System/Base.php
+++ b/CRM/Utils/System/Base.php
@@ -7,25 +7,31 @@ abstract class CRM_Utils_System_Base {
   /**
    * Deprecated property to check if this is a drupal install. The correct method is to have functions on the UF classes for all UF specific
    * functions and leave the codebase oblivious to the type of CMS
+   *
    * @deprecated
    * @var bool
+   *   TRUE, if the CMS is Drupal.
    */
   var $is_drupal = FALSE;
 
   /**
    * Deprecated property to check if this is a joomla install. The correct method is to have functions on the UF classes for all UF specific
    * functions and leave the codebase oblivious to the type of CMS
+   *
    * @deprecated
    * @var bool
+   *   TRUE, if the CMS is Joomla!.
    */
   var $is_joomla = FALSE;
 
-    /**
-     * deprecated property to check if this is a wordpress install. The correct method is to have functions on the UF classes for all UF specific
-     * functions and leave the codebase oblivious to the type of CMS
-     * @deprecated
-     * @var bool
-     */
+  /**
+   * deprecated property to check if this is a wordpress install. The correct method is to have functions on the UF classes for all UF specific
+   * functions and leave the codebase oblivious to the type of CMS
+   *
+   * @deprecated
+   * @var bool
+   *   TRUE, if the CMS is WordPress.
+   */
   var $is_wordpress = FALSE;
 
   /**
@@ -35,8 +41,9 @@ abstract class CRM_Utils_System_Base {
    */
   var $supports_UF_Logging = FALSE;
 
-  /*
-   * Does the CMS allow CMS forms to be extended by hooks
+  /**
+   * @var bool
+   *   TRUE, if the CMS allows CMS forms to be extended by hooks.
    */
   var $supports_form_extensions = FALSE;
 
@@ -44,11 +51,14 @@ abstract class CRM_Utils_System_Base {
    * If we are using a theming system, invoke theme, else just print the
    * content
    *
-   * @param string  $content the content that will be themed
-   * @param boolean $print   are we displaying to the screen or bypassing theming?
-   * @param boolean $maintenance  for maintenance mode
+   * @param string $content the content that will be themed
+   * @param boolean $print are we displaying to the screen or bypassing theming?
+   * @param boolean $maintenance for maintenance mode
    *
-   * @return void           prints content on stdout
+   * @throws Exception
+   * @return string|null
+   *   NULL, If $print is FALSE, and some other criteria match up.
+   *   The themed string, otherwise.
    */
   public function theme(&$content, $print = FALSE, $maintenance = FALSE) {
     $ret = FALSE;
@@ -83,7 +93,7 @@ abstract class CRM_Utils_System_Base {
         require_once (ABSPATH . 'wp-admin/admin-header.php');
       }
       else {
-        // FIX ME: we need to figure out to replace civicrm content on the frontend pages
+        // FIXME: we need to figure out to replace civicrm content on the frontend pages
       }
     }
 
@@ -113,11 +123,11 @@ abstract class CRM_Utils_System_Base {
    * Format the url as per language Negotiation.
    *
    * @param string $url
-   *
    * @param bool $addLanguagePart
    * @param bool $removeLanguagePart
    *
-   * @return string $url, formatted url.
+   * @return string
+   *   Formatted url.
    * @static
    */
   function languageNegotiationURL(
@@ -131,7 +141,8 @@ abstract class CRM_Utils_System_Base {
   /**
    * Determine the location of the CMS root.
    *
-   * @return string|NULL local file system path to CMS root, or NULL if it cannot be determined
+   * @return string|null
+   *   Local file system path to CMS root, or NULL if it cannot be determined
    */
   public function cmsRootPath() {
     return NULL;
@@ -163,8 +174,8 @@ abstract class CRM_Utils_System_Base {
   /**
    * Set a init session with user object
    *
-   * @param array $data  array with user specific data
-   *
+   * @param array $data
+   *   Array with user specific data
    */
   public function setUserSession($data) {
     list($userID, $ufID) = $data;
@@ -191,9 +202,9 @@ abstract class CRM_Utils_System_Base {
   /**
    * Return default Site Settings
    *
-   * @param $dir
+   * @param string $dir
    *
-   * @return array array
+   * @return array
    * - $url, (Joomla - non admin url)
    * - $siteName,
    * - $siteRoot
@@ -209,7 +220,7 @@ abstract class CRM_Utils_System_Base {
    * e.g. for drupal: records a watchdog message about the new session, saves the login timestamp,
    * calls hook_user op 'login' and generates a new session.
    *
-   * @param array params
+   * @param array $params
    *
    * FIXME: Document values accepted/required by $params
    */
@@ -230,11 +241,8 @@ abstract class CRM_Utils_System_Base {
 
   /**
    * Get timezone from CMS
-   * @return boolean|string
-   */
-  /**
-   * Get timezone from Drupal
-   * @return boolean|string
+   *
+   * @return string|false|null
    */
   public function getTimeZoneOffset(){
     $timezone = $this->getTimeZoneString();
@@ -258,7 +266,9 @@ abstract class CRM_Utils_System_Base {
 
   /**
    * Over-ridable function to get timezone as a string eg.
-   * @return string Timezone e.g. 'America/Los_Angeles'
+   *
+   * @return string
+   *   Time zone, e.g. 'America/Los_Angeles'
    */
   public function getTimeZoneString() {
     return date_default_timezone_get();
-- 
2.25.1