From 6389e5c14d32d134ad94e4b72996de90b0786ea8 Mon Sep 17 00:00:00 2001
From: Jaime Perez Crespo <jaime.perez@uninett.no>
Date: Fri, 5 Feb 2016 13:28:58 +0100
Subject: [PATCH] Fix phpdoc in the new SimpleSAML\Locale\Language class.
---
lib/SimpleSAML/Locale/Language.php | 48 +++++++++++++++++-------------
1 file changed, 27 insertions(+), 21 deletions(-)
diff --git a/lib/SimpleSAML/Locale/Language.php b/lib/SimpleSAML/Locale/Language.php
index 059d562d1..11e5b6a8c 100644
--- a/lib/SimpleSAML/Locale/Language.php
+++ b/lib/SimpleSAML/Locale/Language.php
@@ -13,8 +13,7 @@ namespace SimpleSAML\Locale;
class Language {
/**
- * This is the default language map. It is used to map languages codes from the user agent to
- * other language codes.
+ * This is the default language map. It is used to map languages codes from the user agent to other language codes.
*/
private static $defaultLanguageMap = array('nb' => 'no');
@@ -33,8 +32,7 @@ class Language {
/**
* Constructor
*
- * @param $configuration Configuration object
- * @param $defaultDictionary The default dictionary where tags will come from.
+ * @param \SimpleSAML_Configuration $configuration Configuration object
*/
function __construct(\SimpleSAML_Configuration $configuration) {
$this->configuration = $configuration;
@@ -49,10 +47,10 @@ class Language {
/**
- * setLanguage() will set a cookie for the user's browser to remember what language
- * was selected
+ * This method will set a cookie for the user's browser to remember what language was selected.
*
- * @param $language Language code for the language to set.
+ * @param string $language Language code for the language to set.
+ * @param boolean $setLanguageCookie Whether to set the language cookie or not. Defaults to true.
*/
public function setLanguage($language, $setLanguageCookie = TRUE) {
$language = strtolower($language);
@@ -65,11 +63,12 @@ class Language {
}
/**
- * getLanguage() will return the language selected by the user, or the default language
- * This function first looks for a cached language code,
- * then checks for a language cookie,
- * then it tries to calculate the preferred language from HTTP headers.
- * Last it returns the default language.
+ * This method will return the language selected by the user, or the default language. It looks first for a cached
+ * language code, then checks for a language cookie, then it tries to calculate the preferred language from HTTP
+ * headers.
+ *
+ * @return string The language selected by the user according to the processing rules specified, or the default
+ * language in any other case.
*/
public function getLanguage() {
@@ -107,10 +106,10 @@ class Language {
/**
- * This function gets the prefered language for the user based on the Accept-Language http header.
+ * This method returns the preferred language for the user based on the Accept-Language HTTP header.
*
- * @return The prefered language based on the Accept-Language http header, or NULL if none of the
- * languages in the header were available.
+ * @return string The preferred language based on the Accept-Language HTTP header, or null if none of the languages
+ * in the header is available.
*/
private function getHTTPLanguage() {
$languageScore = \SimpleSAML_Utilities::getAcceptLanguage();
@@ -152,14 +151,18 @@ class Language {
/**
- * Returns the language default (from configuration)
+ * Return the default language according to configuration.
+ *
+ * @return string The default language that has been configured. Defaults to english if not configured.
*/
public function getDefaultLanguage() {
return $this->configuration->getString('language.default', 'en');
}
/**
- * Returns a list of all available languages.
+ * Return a list of all languages available.
+ *
+ * @return array An array holding all the languages available.
*/
public function getLanguageList() {
$thisLang = $this->getLanguage();
@@ -171,7 +174,9 @@ class Language {
}
/**
- * Return TRUE if language is Right-to-Left.
+ * Check whether a language is right-to-left or not.
+ *
+ * @return boolean True if the language is right-to-left, false otherwise.
*/
public function isLanguageRTL() {
$rtlLanguages = $this->configuration->getArray('language.rtl', array());
@@ -186,7 +191,7 @@ class Language {
/**
* Retrieve the user-selected language from a cookie.
*
- * @return string|NULL The language, or NULL if unset.
+ * @return string|null The selected language or null if unset.
*/
public static function getLanguageCookie() {
$config = \SimpleSAML_Configuration::getInstance();
@@ -205,9 +210,10 @@ class Language {
/**
- * Set the user-selected language in a cookie.
+ * This method will attempt to set the user-selected language in a cookie. It will do nothing if the language
+ * specified is not in the list of available languages, or the headers have already been sent to the browser.
*
- * @param string $language The language.
+ * @param string $language The language set by the user.
*/
public static function setLanguageCookie($language) {
assert('is_string($language)');
--
GitLab