summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorJennifer Hodgdon2013-01-10 23:41:15 (GMT)
committerJennifer Hodgdon2013-01-10 23:41:15 (GMT)
commit17fbe8599580f9abf0feb825ed6033b747263fa4 (patch)
tree38b531900b3f4197d811b61842df072646fc0ff8
parent2bd70556c23a91678aac2e5f53e203b38a7a63cf (diff)
Issue #1347914 by Albert Volkman, Lars Toomre: API docs fix-up for Filter module
-rw-r--r--core/modules/filter/filter.admin-rtl.css2
-rw-r--r--core/modules/filter/filter.admin.inc13
-rw-r--r--core/modules/filter/filter.module65
-rw-r--r--core/modules/filter/filter.pages.inc9
-rw-r--r--core/modules/filter/lib/Drupal/filter/Tests/FilterAdminTest.php12
-rw-r--r--core/modules/filter/lib/Drupal/filter/Tests/FilterCrudTest.php4
-rw-r--r--core/modules/filter/lib/Drupal/filter/Tests/FilterDefaultFormatTest.php5
-rw-r--r--core/modules/filter/lib/Drupal/filter/Tests/FilterFormatAccessTest.php47
-rw-r--r--core/modules/filter/lib/Drupal/filter/Tests/FilterHooksTest.php2
-rw-r--r--core/modules/filter/lib/Drupal/filter/Tests/FilterSecurityTest.php7
-rw-r--r--core/modules/filter/lib/Drupal/filter/Tests/FilterSettingsTest.php5
-rw-r--r--core/modules/filter/lib/Drupal/filter/Tests/FilterUnitTest.php8
12 files changed, 133 insertions, 46 deletions
diff --git a/core/modules/filter/filter.admin-rtl.css b/core/modules/filter/filter.admin-rtl.css
index 10620bf..0370a98 100644
--- a/core/modules/filter/filter.admin-rtl.css
+++ b/core/modules/filter/filter.admin-rtl.css
@@ -1,7 +1,7 @@
/**
* @file
- * RTL admin styling for the Filter module.
+ * Right-to-Left administrative styling for the Filter module.
*/
/**
diff --git a/core/modules/filter/filter.admin.inc b/core/modules/filter/filter.admin.inc
index a62f8e3..e067199 100644
--- a/core/modules/filter/filter.admin.inc
+++ b/core/modules/filter/filter.admin.inc
@@ -2,11 +2,11 @@
/**
* @file
- * Admin page callbacks for the Filter module.
+ * Administrative page callbacks for the Filter module.
*/
/**
- * Form constructor for a form to list and reorder text formats.
+ * Page callback: Form constructor for a form to list and reorder text formats.
*
* @see filter_menu()
* @see filter_admin_overview_submit()
@@ -103,6 +103,7 @@ function filter_admin_overview_submit($form, &$form_state) {
* enabled (1) or not (0). Defaults to 1.
* - weight: (optional) The weight of the text format, which controls its
* placement in text format lists. If omitted, the weight is set to 0.
+ * Defaults to NULL.
*
* @return
* A form array.
@@ -129,8 +130,8 @@ function filter_admin_format_page($format = NULL) {
* save. If this corresponds to an existing text format, that format will be
* updated; otherwise, a new format will be created.
* - name: The title of the text format.
- * - cache: An integer indicating whether the text format is cacheable (1) or
- * not (0). Defaults to 1.
+ * - cache: (optional) An integer indicating whether the text format is
+ * cacheable (1) or not (0). Defaults to 1.
* - status: (optional) An integer indicating whether the text format is
* enabled (1) or not (0). Defaults to 1.
* - weight: (optional) The weight of the text format, which controls its
@@ -283,7 +284,7 @@ function filter_admin_format_form($form, &$form_state, $format) {
/**
* Returns HTML for a text format's filter order form.
*
- * @param $variables
+ * @param array $variables
* An associative array containing:
* - element: A render element representing the form.
*
@@ -365,7 +366,7 @@ function filter_admin_format_form_submit($form, &$form_state) {
}
/**
- * Form constructor for the text format deletion confirmation form.
+ * Page callback: Form constructor to confirm the text format deletion.
*
* @param $format
* An object representing a text format.
diff --git a/core/modules/filter/filter.module b/core/modules/filter/filter.module
index c4b596a..182bbb1 100644
--- a/core/modules/filter/filter.module
+++ b/core/modules/filter/filter.module
@@ -359,6 +359,12 @@ function filter_format_exists($format_id) {
/**
* Displays a text format form title.
*
+ * @param object $format_id
+ * A format object.
+ *
+ * @return string
+ * The name of the format.
+ *
* @see filter_menu()
*/
function filter_admin_format_title($format) {
@@ -434,7 +440,8 @@ function filter_modules_disabled($modules) {
*
* @param $account
* (optional) If provided, only those formats that are allowed for this user
- * account will be returned. All formats will be returned otherwise.
+ * account will be returned. All formats will be returned otherwise. Defaults
+ * to NULL.
*
* @return
* An array of text format objects, keyed by the format ID and ordered by
@@ -547,7 +554,7 @@ function filter_get_formats_by_role($rid) {
*
* @param $account
* (optional) The user account to check. Defaults to the currently logged-in
- * user.
+ * user. Defaults to NULL.
*
* @return
* The ID of the user's default text format.
@@ -612,15 +619,15 @@ function filter_get_filter_types_by_format($format_id) {
* format is initialized to output plain text. Installation profiles and site
* administrators have the freedom to configure it further.
*
- * Note that the fallback format is completely distinct from the default
- * format, which differs per user and is simply the first format which that
- * user has access to. The default and fallback formats are only guaranteed to
- * be the same for users who do not have access to any other format; otherwise,
- * the fallback format's weight determines its placement with respect to the
- * user's other formats.
+ * Note that the fallback format is completely distinct from the default format,
+ * which differs per user and is simply the first format which that user has
+ * access to. The default and fallback formats are only guaranteed to be the
+ * same for users who do not have access to any other format; otherwise, the
+ * fallback format's weight determines its placement with respect to the user's
+ * other formats.
*
- * Any modules implementing a format deletion functionality must not delete
- * this format.
+ * Any modules implementing a format deletion functionality must not delete this
+ * format.
*
* @return
* The ID of the fallback text format.
@@ -640,6 +647,9 @@ function filter_fallback_format() {
/**
* Returns the title of the fallback text format.
+ *
+ * @return string
+ * The title of the fallback text format.
*/
function filter_fallback_format_title() {
$fallback_format = filter_format_load(filter_fallback_format());
@@ -648,6 +658,9 @@ function filter_fallback_format_title() {
/**
* Returns a list of all filters provided by modules.
+ *
+ * @return array
+ * An array of filter formats.
*/
function filter_get_filters() {
$filters = &drupal_static(__FUNCTION__, array());
@@ -799,16 +812,17 @@ function filter_list_format($format_id) {
* @param $text
* The text to be filtered.
* @param $format_id
- * The format ID of the text to be filtered. If no format is assigned, the
- * fallback format will be used.
+ * (optional) The format ID of the text to be filtered. If no format is
+ * assigned, the fallback format will be used. Defaults to NULL.
* @param $langcode
- * Optional: the language code of the text to be filtered, e.g. 'en' for
+ * (optional) The language code of the text to be filtered, e.g. 'en' for
* English. This allows filters to be language aware so language specific
- * text replacement can be implemented.
+ * text replacement can be implemented. Defaults to an empty string.
* @param $cache
- * Boolean whether to cache the filtered output in the {cache_filter} table.
- * The caller may set this to FALSE when the output is already cached
- * elsewhere to avoid duplicate cache lookups and storage.
+ * (optional) A Boolean indicating whether to cache the filtered output in the
+ * {cache_filter} table. The caller may set this to FALSE when the output is
+ * already cached elsewhere to avoid duplicate cache lookups and storage.
+ * Defaults to FALSE.
* @param array $filter_types_to_skip
* (optional) An array of filter types to skip, or an empty array (default)
* to skip no filter types. All of the format's filters will be applied,
@@ -1071,7 +1085,7 @@ function filter_form_access_denied($element) {
/**
* Returns HTML for a text format-enabled form element.
*
- * @param $variables
+ * @param array $variables
* An associative array containing:
* - element: A render element containing #children and #description.
*
@@ -1096,7 +1110,7 @@ function theme_text_format_wrapper($variables) {
* An object representing the text format.
* @param $account
* (optional) The user account to check access for; if omitted, the currently
- * logged-in user is used.
+ * logged-in user is used. Defaults to NULL.
*
* @return
* Boolean TRUE if the user is allowed to access the given format.
@@ -1232,9 +1246,11 @@ function filter_dom_serialize($dom_document) {
* @param $dom_element
* The element potentially containing a CDATA node.
* @param $comment_start
- * String to use as a comment start marker to escape the CDATA declaration.
+ * (optional) A string to use as a comment start marker to escape the CDATA
+ * declaration. Defaults to '//'.
* @param $comment_end
- * String to use as a comment end marker to escape the CDATA declaration.
+ * (optional) A string to use as a comment end marker to escape the CDATA
+ * declaration. Defaults to an empty string.
*/
function filter_dom_serialize_escape_cdata_element($dom_document, $dom_element, $comment_start = '//', $comment_end = '') {
foreach ($dom_element->childNodes as $node) {
@@ -1269,7 +1285,7 @@ function theme_filter_tips_more_info() {
/**
* Returns HTML for guidelines for a text format.
*
- * @param $variables
+ * @param array $variables
* An associative array containing:
* - format: An object representing a text format.
*
@@ -1695,8 +1711,9 @@ function _filter_url_parse_partial_links($match) {
* An array containing matches to replace from preg_replace_callback(),
* whereas $match[1] is expected to contain the content to be filtered.
* @param $escape
- * (optional) Boolean whether to escape (TRUE) or unescape comments (FALSE).
- * Defaults to neither. If TRUE, statically cached $comments are reset.
+ * (optional) A Boolean indicating whether to escape (TRUE) or unescape
+ * comments (FALSE). Defaults to NULL, indicating neither. If TRUE, statically
+ * cached $comments are reset.
*/
function _filter_url_escape_comments($match, $escape = NULL) {
static $mode, $comments = array();
diff --git a/core/modules/filter/filter.pages.inc b/core/modules/filter/filter.pages.inc
index dec59c3..5b20d4f 100644
--- a/core/modules/filter/filter.pages.inc
+++ b/core/modules/filter/filter.pages.inc
@@ -8,7 +8,14 @@
/**
* Page callback: Displays a page with long filter tips.
*
+ * @param $format
+ * (optional) A filter format. Defaults to NULL.
+ *
+ * @return string
+ * An HTML-formatted string.
+ *
* @see filter_menu()
+ * @see theme_filter_tips()
*/
function filter_tips_long($format = NULL) {
if (!empty($format)) {
@@ -23,7 +30,7 @@ function filter_tips_long($format = NULL) {
/**
* Returns HTML for a set of filter tips.
*
- * @param $variables
+ * @param array $variables
* An associative array containing:
* - tips: An array containing descriptions and a CSS ID in the form of
* 'module-name/filter-id' (only used when $long is TRUE) for each
diff --git a/core/modules/filter/lib/Drupal/filter/Tests/FilterAdminTest.php b/core/modules/filter/lib/Drupal/filter/Tests/FilterAdminTest.php
index 9a09a76..c2b76d2 100644
--- a/core/modules/filter/lib/Drupal/filter/Tests/FilterAdminTest.php
+++ b/core/modules/filter/lib/Drupal/filter/Tests/FilterAdminTest.php
@@ -9,7 +9,16 @@ namespace Drupal\filter\Tests;
use Drupal\simpletest\WebTestBase;
+/**
+ * Tests the administrative functionality of the Filter module.
+ */
class FilterAdminTest extends WebTestBase {
+
+ /**
+ * The installation profile to use with this test.
+ *
+ * @var string
+ */
protected $profile = 'standard';
public static function getInfo() {
@@ -36,6 +45,9 @@ class FilterAdminTest extends WebTestBase {
$this->drupalLogin($this->admin_user);
}
+ /**
+ * Tests the format administration functionality.
+ */
function testFormatAdmin() {
// Add text format.
$this->drupalGet('admin/config/content/formats');
diff --git a/core/modules/filter/lib/Drupal/filter/Tests/FilterCrudTest.php b/core/modules/filter/lib/Drupal/filter/Tests/FilterCrudTest.php
index 766736f..7b4c6f5 100644
--- a/core/modules/filter/lib/Drupal/filter/Tests/FilterCrudTest.php
+++ b/core/modules/filter/lib/Drupal/filter/Tests/FilterCrudTest.php
@@ -82,7 +82,7 @@ class FilterCrudTest extends WebTestBase {
}
/**
- * Verify that a text format is properly stored.
+ * Verifies that a text format is properly stored.
*/
function verifyTextFormat($format) {
$t_args = array('%format' => $format->name);
@@ -120,7 +120,7 @@ class FilterCrudTest extends WebTestBase {
}
/**
- * Verify that filters are properly stored for a text format.
+ * Verifies that filters are properly stored for a text format.
*/
function verifyFilters($format) {
// Verify filter database records.
diff --git a/core/modules/filter/lib/Drupal/filter/Tests/FilterDefaultFormatTest.php b/core/modules/filter/lib/Drupal/filter/Tests/FilterDefaultFormatTest.php
index 04fa520..103d777 100644
--- a/core/modules/filter/lib/Drupal/filter/Tests/FilterDefaultFormatTest.php
+++ b/core/modules/filter/lib/Drupal/filter/Tests/FilterDefaultFormatTest.php
@@ -9,6 +9,9 @@ namespace Drupal\filter\Tests;
use Drupal\simpletest\WebTestBase;
+/**
+ * Tests the default filter functionality in the Filter module.
+ */
class FilterDefaultFormatTest extends WebTestBase {
public static function getInfo() {
return array(
@@ -64,7 +67,7 @@ class FilterDefaultFormatTest extends WebTestBase {
}
/**
- * Rebuild text format and permission caches in the thread running the tests.
+ * Rebuilds text format and permission caches in the thread running the tests.
*/
protected function resetFilterCaches() {
filter_formats_reset();
diff --git a/core/modules/filter/lib/Drupal/filter/Tests/FilterFormatAccessTest.php b/core/modules/filter/lib/Drupal/filter/Tests/FilterFormatAccessTest.php
index 4636610..a71a9e9 100644
--- a/core/modules/filter/lib/Drupal/filter/Tests/FilterFormatAccessTest.php
+++ b/core/modules/filter/lib/Drupal/filter/Tests/FilterFormatAccessTest.php
@@ -9,11 +9,43 @@ namespace Drupal\filter\Tests;
use Drupal\simpletest\WebTestBase;
+/**
+ * Tests the filter format access functionality in the Filter module.
+ */
class FilterFormatAccessTest extends WebTestBase {
+ /**
+ * A user with administrative permissions.
+ *
+ * @var object
+ */
protected $admin_user;
+
+ /**
+ * A user with 'administer filters' permission.
+ *
+ * @var object
+ */
protected $filter_admin_user;
+
+ /**
+ * A user with permission to create and edit own content.
+ *
+ * @var object
+ */
protected $web_user;
+
+ /**
+ * An object representing an allowed text format.
+ *
+ * @var object
+ */
protected $allowed_format;
+
+ /**
+ * An object representing a disallowed text format.
+ *
+ * @var object
+ */
protected $disallowed_format;
public static function getInfo() {
@@ -69,6 +101,9 @@ class FilterFormatAccessTest extends WebTestBase {
));
}
+ /**
+ * Tests the Filter format access permissions functionality.
+ */
function testFormatPermissions() {
// Make sure that a regular user only has access to the text format they
// were granted access to, as well to the fallback format.
@@ -154,11 +189,11 @@ class FilterFormatAccessTest extends WebTestBase {
/**
* Tests editing a page using a disallowed text format.
*
- * Verifies that regular users and administrators are able to edit a page,
- * but not allowed to change the fields which use an inaccessible text
- * format. Also verifies that fields which use a text format that does not
- * exist can be edited by administrators only, but that the administrator is
- * forced to choose a new format before saving the page.
+ * Verifies that regular users and administrators are able to edit a page, but
+ * not allowed to change the fields which use an inaccessible text format.
+ * Also verifies that fields which use a text format that does not exist can
+ * be edited by administrators only, but that the administrator is forced to
+ * choose a new format before saving the page.
*/
function testFormatWidgetPermissions() {
$langcode = LANGUAGE_NOT_SPECIFIED;
@@ -274,7 +309,7 @@ class FilterFormatAccessTest extends WebTestBase {
}
/**
- * Rebuild text format and permission caches in the thread running the tests.
+ * Rebuilds text format and permission caches in the thread running the tests.
*/
protected function resetFilterCaches() {
filter_formats_reset();
diff --git a/core/modules/filter/lib/Drupal/filter/Tests/FilterHooksTest.php b/core/modules/filter/lib/Drupal/filter/Tests/FilterHooksTest.php
index f01b4d2..496a5f3 100644
--- a/core/modules/filter/lib/Drupal/filter/Tests/FilterHooksTest.php
+++ b/core/modules/filter/lib/Drupal/filter/Tests/FilterHooksTest.php
@@ -10,7 +10,7 @@ namespace Drupal\filter\Tests;
use Drupal\simpletest\WebTestBase;
/**
- * Tests for filter hook invocation.
+ * Tests for Filter's hook invocations.
*/
class FilterHooksTest extends WebTestBase {
diff --git a/core/modules/filter/lib/Drupal/filter/Tests/FilterSecurityTest.php b/core/modules/filter/lib/Drupal/filter/Tests/FilterSecurityTest.php
index 813d717..5928a4d 100644
--- a/core/modules/filter/lib/Drupal/filter/Tests/FilterSecurityTest.php
+++ b/core/modules/filter/lib/Drupal/filter/Tests/FilterSecurityTest.php
@@ -21,6 +21,13 @@ class FilterSecurityTest extends WebTestBase {
*/
public static $modules = array('node', 'php', 'filter_test');
+ /**
+ * A user with administrative permissions.
+ *
+ * @var object
+ */
+ protected $admin_user;
+
public static function getInfo() {
return array(
'name' => 'Security',
diff --git a/core/modules/filter/lib/Drupal/filter/Tests/FilterSettingsTest.php b/core/modules/filter/lib/Drupal/filter/Tests/FilterSettingsTest.php
index 0a6c00c..6d2ab99 100644
--- a/core/modules/filter/lib/Drupal/filter/Tests/FilterSettingsTest.php
+++ b/core/modules/filter/lib/Drupal/filter/Tests/FilterSettingsTest.php
@@ -13,6 +13,11 @@ use Drupal\simpletest\WebTestBase;
* Tests filter settings.
*/
class FilterSettingsTest extends WebTestBase {
+ /**
+ * The installation profile to use with this test class.
+ *
+ * @var string
+ */
protected $profile = 'testing';
public static function getInfo() {
diff --git a/core/modules/filter/lib/Drupal/filter/Tests/FilterUnitTest.php b/core/modules/filter/lib/Drupal/filter/Tests/FilterUnitTest.php
index b2264a4..de9f194 100644
--- a/core/modules/filter/lib/Drupal/filter/Tests/FilterUnitTest.php
+++ b/core/modules/filter/lib/Drupal/filter/Tests/FilterUnitTest.php
@@ -981,9 +981,9 @@ body {color:red}
* @param $needle
* Lowercase, plain text to look for.
* @param $message
- * Message to display if failed.
+ * (optional) Message to display if failed. Defaults to an empty string.
* @param $group
- * The group this message belongs to, defaults to 'Other'.
+ * (optional) The group this message belongs to. Defaults to 'Other'.
* @return
* TRUE on pass, FALSE on fail.
*/
@@ -1005,9 +1005,9 @@ body {color:red}
* @param $needle
* Lowercase, plain text to look for.
* @param $message
- * Message to display if failed.
+ * (optional) Message to display if failed. Defaults to an empty string.
* @param $group
- * The group this message belongs to, defaults to 'Other'.
+ * (optional) The group this message belongs to. Defaults to 'Other'.
* @return
* TRUE on pass, FALSE on fail.
*/