diff options
author | webchick <webchick@24967.no-reply.drupal.org> | 2011-12-24 17:51:06 -0800 |
---|---|---|
committer | webchick <webchick@24967.no-reply.drupal.org> | 2011-12-24 17:51:06 -0800 |
commit | 755e486d12dbe1ceb4038bb00a780a13801b56e3 (patch) | |
tree | 626d3ac5c61d23184151fe1885c712d453f364c4 | |
parent | 0dc3499883c782b9bf63749b2e5344ef75d2d558 (diff) | |
download | brdo-755e486d12dbe1ceb4038bb00a780a13801b56e3.tar.gz brdo-755e486d12dbe1ceb4038bb00a780a13801b56e3.tar.bz2 |
Issue #1323720 by xenophyle, xjm: Clean up API docs for block module.
-rw-r--r-- | modules/block/block-admin-display-form.tpl.php | 2 | ||||
-rw-r--r-- | modules/block/block.admin.inc | 25 | ||||
-rw-r--r-- | modules/block/block.module | 65 | ||||
-rw-r--r-- | modules/block/block.tpl.php | 11 |
4 files changed, 63 insertions, 40 deletions
diff --git a/modules/block/block-admin-display-form.tpl.php b/modules/block/block-admin-display-form.tpl.php index 94b610416..17a15e40d 100644 --- a/modules/block/block-admin-display-form.tpl.php +++ b/modules/block/block-admin-display-form.tpl.php @@ -21,6 +21,8 @@ * * @see template_preprocess_block_admin_display_form() * @see theme_block_admin_display() + * + * @ingroup themeable */ ?> <?php diff --git a/modules/block/block.admin.inc b/modules/block/block.admin.inc index f86fe96b9..bd6179063 100644 --- a/modules/block/block.admin.inc +++ b/modules/block/block.admin.inc @@ -57,7 +57,7 @@ function block_admin_display_prepare_blocks($theme) { } /** - * Form builder for the main blocks administration form. + * Form constructor for the main block administration form. * * @param $blocks * An array of blocks, as returned by block_admin_display_prepare_blocks(). @@ -165,7 +165,7 @@ function block_admin_display_form($form, &$form_state, $blocks, $theme, $block_r } /** - * Form submission handler for the main blocks administration form. + * Form submission handler for block_admin_display_form(). * * @see block_admin_display_form() */ @@ -197,10 +197,9 @@ function block_admin_display_form_submit($form, &$form_state) { } /** - * Helper function for sorting blocks on admin/structure/block. + * Sorts active blocks by region, then by weight; sorts inactive blocks by name. * - * Active blocks are sorted by region, then by weight. - * Disabled blocks are sorted by name. + * Callback for usort() in block_admin_display_prepare_blocks(). */ function _block_compare($a, $b) { global $theme_key; @@ -240,7 +239,7 @@ function _block_compare($a, $b) { } /** - * Form builder for the block configuration form. + * Form constructor for the block configuration form. * * Also used by block_add_block_form() for adding a new custom block. * @@ -441,7 +440,7 @@ function block_admin_configure($form, &$form_state, $module, $delta) { } /** - * Form validation handler for the block configuration form. + * Form validation handler for block_admin_configure(). * * @see block_admin_configure() * @see block_admin_configure_submit() @@ -459,7 +458,7 @@ function block_admin_configure_validate($form, &$form_state) { } /** - * Form submission handler for the block configuration form. + * Form submission handler for block_admin_configure(). * * @see block_admin_configure() * @see block_admin_configure_validate() @@ -519,7 +518,7 @@ function block_admin_configure_submit($form, &$form_state) { } /** - * Form builder for the add block form. + * Form constructor for the add block form. * * @see block_add_block_form_validate() * @see block_add_block_form_submit() @@ -530,7 +529,7 @@ function block_add_block_form($form, &$form_state) { } /** - * Form validation handler for the add block form. + * Form validation handler for block_add_block_form(). * * @see block_add_block_form() * @see block_add_block_form_submit() @@ -544,7 +543,7 @@ function block_add_block_form_validate($form, &$form_state) { } /** - * Form submission handler for the add block form. + * Form submission handler for block_add_block_form(). * * Saves the new custom block. * @@ -609,7 +608,7 @@ function block_add_block_form_submit($form, &$form_state) { } /** - * Form builder for the custom block deletion form. + * Form constructor for the custom block deletion form. * * @param $module * The name of the module that implements the block to be deleted. This should @@ -629,7 +628,7 @@ function block_custom_block_delete($form, &$form_state, $module, $delta) { } /** - * Form submission handler for the custom block deletion form. + * Form submission handler for block_custom_block_delete(). * * @see block_custom_block_delete() */ diff --git a/modules/block/block.module b/modules/block/block.module index 754febd27..24319089e 100644 --- a/modules/block/block.module +++ b/modules/block/block.module @@ -16,27 +16,27 @@ define('BLOCK_REGION_NONE', -1); define('BLOCK_CUSTOM_FIXED', 0); /** - * Show this block by default, but let individual users hide it. + * Shows this block by default, but lets individual users hide it. */ define('BLOCK_CUSTOM_ENABLED', 1); /** - * Hide this block by default but let individual users show it. + * Hides this block by default but lets individual users show it. */ define('BLOCK_CUSTOM_DISABLED', 2); /** - * Show this block on every page except the listed pages. + * Shows this block on every page except the listed pages. */ define('BLOCK_VISIBILITY_NOTLISTED', 0); /** - * Show this block on only the listed pages. + * Shows this block on only the listed pages. */ define('BLOCK_VISIBILITY_LISTED', 1); /** - * Show this block if the associated PHP code returns TRUE. + * Shows this block if the associated PHP code returns TRUE. */ define('BLOCK_VISIBILITY_PHP', 2); @@ -249,7 +249,7 @@ function block_block_view($delta = '') { /** * Implements hook_page_build(). * - * Render blocks into their regions. + * Renders blocks into their regions. */ function block_page_build(&$page) { global $theme; @@ -305,10 +305,13 @@ function block_page_build(&$page) { } /** - * Get a renderable array of a region containing all enabled blocks. + * Gets a renderable array of a region containing all enabled blocks. * * @param $region * The requested region. + * + * @return + * A renderable array of a region containing all enabled blocks. */ function block_get_blocks_by_region($region) { $build = array(); @@ -319,10 +322,11 @@ function block_get_blocks_by_region($region) { } /** - * Get an array of blocks suitable for drupal_render(). + * Gets an array of blocks suitable for drupal_render(). * * @param $list * A list of blocks such as that returned by block_list(). + * * @return * A renderable array. */ @@ -353,7 +357,7 @@ function _block_get_renderable_array($list = array()) { } /** - * Update the 'block' DB table with the blocks currently exported by modules. + * Updates the 'block' DB table with the blocks currently exported by modules. * * @param $theme * The theme to rehash blocks for. If not provided, defaults to the currently @@ -473,6 +477,7 @@ function _block_rehash($theme = NULL) { * * @param $bid * ID of the block to get information for. + * * @return * Associative array of information stored in the database for this block. * Array keys: @@ -486,7 +491,14 @@ function block_custom_block_get($bid) { } /** - * Define the custom block form. + * Form constructor for the custom block form. + * + * @param $edit + * (optional) An associative array of information retrieved by + * block_custom_get_block() if an existing block is being edited, or an empty + * array otherwise. Defaults to array(). + * + * @ingroup forms */ function block_custom_block_form($edit = array()) { $edit += array( @@ -528,6 +540,7 @@ function block_custom_block_form($edit = array()) { * - format: Filter ID of the filter format for the body. * @param $delta * Block ID of the block to save. + * * @return * Always returns TRUE. */ @@ -544,7 +557,7 @@ function block_custom_block_save($edit, $delta) { } /** - * Implements hook_form_FORM_ID_alter(). + * Implements hook_form_FORM_ID_alter() for user_profile_form(). */ function block_form_user_profile_form_alter(&$form, &$form_state) { if ($form['#user_category'] == 'account') { @@ -588,7 +601,10 @@ function block_user_presave(&$edit, $account, $category) { } /** - * Initialize blocks for enabled themes. + * Initializes blocks for enabled themes. + * + * @param $theme_list + * An array of theme names. */ function block_themes_enabled($theme_list) { foreach ($theme_list as $theme) { @@ -597,7 +613,7 @@ function block_themes_enabled($theme_list) { } /** - * Assign an initial, default set of blocks for a theme. + * Assigns an initial, default set of blocks for a theme. * * This function is called the first time a new theme is enabled. The new theme * gets a copy of the default theme's blocks, with the difference that if a @@ -628,7 +644,7 @@ function block_theme_initialize($theme) { } /** - * Return all blocks in the specified region for the current user. + * Returns all blocks in the specified region for the current user. * * @param $region * The name of a region. @@ -640,7 +656,7 @@ function block_theme_initialize($theme) { * empty to see how many columns are going to be displayed. * * @todo - * Now that the blocks table has a primary key, we should use that as the + * Now that the block table has a primary key, we should use that as the * array key instead of MODULE_DELTA. */ function block_list($region) { @@ -662,7 +678,7 @@ function block_list($region) { } /** - * Load a block object from the database. + * Loads a block object from the database. * * @param $module * Name of the module that implements the block to load. @@ -690,7 +706,10 @@ function block_load($module, $delta) { } /** - * Load blocks information from the database. + * Loads blocks' information from the database. + * + * @return + * An array of blocks grouped by region. */ function _block_load_blocks() { global $theme_key; @@ -721,8 +740,8 @@ function _block_load_blocks() { /** * Implements hook_block_list_alter(). * - * Check the page, user role and user specific visibilty settings. - * Remove the block if the visibility conditions are not met. + * Checks the page, user role, and user-specific visibilty settings. + * Removes the block if the visibility conditions are not met. */ function block_block_list_alter(&$blocks) { global $user, $theme_key; @@ -916,9 +935,9 @@ function block_flush_caches() { } /** - * Process variables for block.tpl.php + * Processes variables for block.tpl.php. * - * Prepare the values passed to the theme_block function to be passed + * Prepares the values passed to the theme_block function to be passed * into a pluggable template engine. Uses block properties to generate a * series of template file suggestions. If none are found, the default * block.tpl.php is used. @@ -967,7 +986,7 @@ function template_preprocess_block(&$variables) { /** * Implements hook_user_role_delete(). * - * Remove deleted role from blocks that use it. + * Removes deleted role from blocks that use it. */ function block_user_role_delete($role) { db_delete('block_role') @@ -1019,7 +1038,7 @@ function block_admin_paths() { /** * Implements hook_modules_uninstalled(). * - * Cleanup {block} and {block_role} tables from modules' blocks. + * Cleans up {block} and {block_role} tables from modules' blocks. */ function block_modules_uninstalled($modules) { db_delete('block') diff --git a/modules/block/block.tpl.php b/modules/block/block.tpl.php index b1946374a..f0bfa5cab 100644 --- a/modules/block/block.tpl.php +++ b/modules/block/block.tpl.php @@ -12,11 +12,12 @@ * - $block->region: The block region embedding the current block. * - $classes: String of classes that can be used to style contextually through * CSS. It can be manipulated through the variable $classes_array from - * preprocess functions. The default values can be one or more of the following: + * preprocess functions. The default values can be one or more of the + * following: * - block: The current template type, i.e., "theming hook". - * - block-[module]: The module generating the block. For example, the user module - * is responsible for handling the default user navigation block. In that case - * the class would be "block-user". + * - block-[module]: The module generating the block. For example, the user + * module is responsible for handling the default user navigation block. In + * that case the class would be 'block-user'. * - $title_prefix (array): An array containing additional output populated by * modules, intended to be displayed in front of the main title tag that * appears in the template. @@ -39,6 +40,8 @@ * @see template_preprocess() * @see template_preprocess_block() * @see template_process() + * + * @ingroup themeable */ ?> <div id="<?php print $block_html_id; ?>" class="<?php print $classes; ?>"<?php print $attributes; ?>> |