Commit 17fbe859 authored by jhodgdon's avatar jhodgdon

Issue #1347914 by Albert Volkman, Lars Toomre: API docs fix-up for Filter module

parent 2bd70556
/**
* @file
* RTL admin styling for the Filter module.
* Right-to-Left administrative styling for the Filter module.
*/
/**
......
......@@ -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.
......
......@@ -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();
......
......@@ -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
......
......@@ -9,7 +9,16 @@
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 @@ function setUp() {
$this->drupalLogin($this->admin_user);
}
/**
* Tests the format administration functionality.
*/
function testFormatAdmin() {
// Add text format.
$this->drupalGet('admin/config/content/formats');
......
......@@ -82,7 +82,7 @@ function testTextFormatCrud() {
}
/**
* 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 @@ function verifyTextFormat($format) {
}
/**
* 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.
......
......@@ -9,6 +9,9 @@
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 @@ function testDefaultTextFormats() {
}
/**
* 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();
......
......@@ -9,11 +9,43 @@
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 @@ function setUp() {
));
}
/**
* 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 @@ function testFormatRoles() {
/**
* 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 @@ function testFormatWidgetPermissions() {
}
/**
* 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();
......
......@@ -10,7 +10,7 @@
use Drupal\simpletest\WebTestBase;
/**
* Tests for filter hook invocation.
* Tests for Filter's hook invocations.
*/
class FilterHooksTest extends WebTestBase {
......
......@@ -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',
......
......@@ -13,6 +13,11 @@
* 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() {
......
......@@ -981,9 +981,9 @@ function testHtmlCorrectorFilter() {
* @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 @@ function assertNormalized($haystack, $needle, $message = '', $group = 'Other') {
* @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.
*/
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment