Commit f0da6c52 authored by jhodgdon's avatar jhodgdon

Issue #1313980 by Lars Toomre: Fix up some docs in node module

parent 01151024
......@@ -8,6 +8,9 @@
/**
* Page callback: Displays the content type admin overview page.
*
* @return array
* An array as expected by drupal_render().
*
* @see node_menu()
*/
function node_overview_types() {
......@@ -63,6 +66,9 @@ function node_overview_types() {
* - type: An object containing the 'type' (machine name) and 'description' of
* the content type.
*
* @return string
* An HTML-formatted string of the description for this node type.
*
* @ingroup themeable
*/
function theme_node_admin_overview($variables) {
......@@ -278,6 +284,12 @@ function node_type_form($form, &$form_state, $type = NULL) {
/**
* Helper function for teaser length choices.
*
* @param int $length
* An integer representing the desired length of the teaser string.
*
* @return string
* A string that reprents the teaser length options.
*/
function _node_characters($length) {
return ($length == 0) ? t('Unlimited') : format_plural($length, '1 character', '@count characters');
......
......@@ -10,8 +10,11 @@
/**
* Page callback: Form constructor for the permission rebuild confirmation form.
*
* @see node_menu()
* @return array
* An array as expected by drupal_render().
*
* @see node_configure_rebuild_confirm_submit()
* @see node_menu()
*/
function node_configure_rebuild_confirm() {
return confirm_form(array(), t('Are you sure you want to rebuild the permissions on site content?'),
......@@ -73,7 +76,7 @@ function node_node_operations() {
* Lists node administration filters that can be applied.
*
* @return
* Associative array of filters.
* An associative array of filters.
*/
function node_filters() {
// Regular filters
......@@ -124,7 +127,7 @@ function node_filters() {
/**
* Applies filters for the node administration overview based on session.
*
* @param $query
* @param Drupal\Core\Database\Query\SelectInterface $query
* A SelectQuery to which the filters should be applied.
*/
function node_build_filter_query(SelectInterface $query) {
......@@ -145,14 +148,15 @@ function node_build_filter_query(SelectInterface $query) {
}
/**
* Returns the node administration filters form object to node_admin_content().
* Returns the node administration filters form array to node_admin_content().
*
* @see node_multiple_delete_confirm()
* @see node_multiple_delete_confirm_submit()
* @see node_admin_nodes()
* @see node_admin_nodes_submit()
* @see node_admin_nodes_validate()
* @see node_filter_form_submit()
* @see node_multiple_delete_confirm()
* @see node_multiple_delete_confirm_submit()
*
* @ingroup forms
*/
function node_filter_form() {
......@@ -231,12 +235,12 @@ function node_filter_form() {
* Form submission handler for node_filter_form().
*
* @see node_admin_content()
* @see node_multiple_delete_confirm()
* @see node_multiple_delete_confirm_submit()
* @see node_admin_nodes()
* @see node_admin_nodes_submit()
* @see node_admin_nodes_validate()
* @see node_filter_form()
* @see node_multiple_delete_confirm()
* @see node_multiple_delete_confirm_submit()
*/
function node_filter_form_submit($form, &$form_state) {
$filters = node_filters();
......@@ -310,6 +314,9 @@ function node_mass_update($nodes, $updates) {
* @param $updates
* Associative array of updates.
*
* @return object
* An updated node object.
*
* @see node_mass_update()
*/
function _node_mass_update_helper($nid, $updates) {
......@@ -325,6 +332,13 @@ function _node_mass_update_helper($nid, $updates) {
/**
* Executes a batch operation for node_mass_update().
*
* @param array $nodes
* An array of node IDs.
* @param array $updates
* Associative array of updates.
* @param array $context
* An array of contextual key/values.
*/
function _node_mass_update_batch_process($nodes, $updates, &$context) {
if (!isset($context['sandbox']['progress'])) {
......@@ -356,6 +370,14 @@ function _node_mass_update_batch_process($nodes, $updates, &$context) {
/**
* Reports the 'finished' status of batch operation for node_mass_update().
*
* @param bool $success
* A boolean indicating whether the batch mass update operation successfully
* concluded.
* @param int $results
* The number of nodes updated via the batch mode process.
* @param array $operations
* An array of function calls (not used in this function).
*/
function _node_mass_update_batch_finished($success, $results, $operations) {
if ($success) {
......@@ -372,14 +394,14 @@ function _node_mass_update_batch_finished($success, $results, $operations) {
/**
* Page callback: Form constructor for the content administration form.
*
* @see node_multiple_delete_confirm()
* @see node_multiple_delete_confirm_submit()
* @see node_admin_nodes()
* @see node_admin_nodes_submit()
* @see node_admin_nodes_validate()
* @see node_filter_form()
* @see node_filter_form_submit()
* @see node_menu()
* @see node_multiple_delete_confirm()
* @see node_multiple_delete_confirm_submit()
*/
function node_admin_content($form, $form_state) {
if (isset($form_state['values']['operation']) && $form_state['values']['operation'] == 'delete') {
......@@ -395,12 +417,13 @@ function node_admin_content($form, $form_state) {
/**
* Returns the admin form object to node_admin_content().
*
* @see node_multiple_delete_confirm()
* @see node_multiple_delete_confirm_submit()
* @see node_admin_nodes_submit()
* @see node_admin_nodes_validate()
* @see node_filter_form()
* @see node_filter_form_submit()
* @see node_multiple_delete_confirm()
* @see node_multiple_delete_confirm_submit()
*
* @ingroup forms
*/
function node_admin_nodes() {
......@@ -592,12 +615,12 @@ function node_admin_nodes() {
* Checks if any nodes have been selected to perform the chosen
* 'Update option' on.
*
* @see node_multiple_delete_confirm()
* @see node_multiple_delete_confirm_submit()
* @see node_admin_nodes()
* @see node_admin_nodes_submit()
* @see node_filter_form()
* @see node_filter_form_submit()
* @see node_multiple_delete_confirm()
* @see node_multiple_delete_confirm_submit()
*/
function node_admin_nodes_validate($form, &$form_state) {
// Error if there are no items to select.
......@@ -611,12 +634,12 @@ function node_admin_nodes_validate($form, &$form_state) {
*
* Executes the chosen 'Update option' on the selected nodes.
*
* @see node_multiple_delete_confirm()
* @see node_multiple_delete_confirm_submit()
* @see node_admin_nodes()
* @see node_admin_nodes_validate()
* @see node_filter_form()
* @see node_filter_form_submit()
* @see node_multiple_delete_confirm()
* @see node_multiple_delete_confirm_submit()
*/
function node_admin_nodes_submit($form, &$form_state) {
$operations = module_invoke_all('node_operations');
......@@ -645,12 +668,12 @@ function node_admin_nodes_submit($form, &$form_state) {
/**
* Multiple node deletion confirmation form for node_admin_content().
*
* @see node_multiple_delete_confirm_submit()
* @see node_admin_nodes()
* @see node_admin_nodes_submit()
* @see node_admin_nodes_validate()
* @see node_filter_form()
* @see node_filter_form_submit()
* @see node_multiple_delete_confirm_submit()
*/
function node_multiple_delete_confirm($form, &$form_state, $nodes) {
$form['nodes'] = array('#prefix' => '<ul>', '#suffix' => '</ul>', '#tree' => TRUE);
......@@ -678,12 +701,12 @@ function node_multiple_delete_confirm($form, &$form_state, $nodes) {
/**
* Form submission handler for node_multiple_delete_confirm().
*
* @see node_multiple_delete_confirm()
* @see node_admin_nodes()
* @see node_admin_nodes_submit()
* @see node_admin_nodes_validate()
* @see node_filter_form()
* @see node_filter_form_submit()
* @see node_multiple_delete_confirm()
*/
function node_multiple_delete_confirm_submit($form, &$form_state) {
if ($form_state['values']['confirm']) {
......
......@@ -454,6 +454,9 @@ function node_install() {
/**
* Implements hook_uninstall().
*
* @see node_ranking()
* @see _node_rankings()
*/
function node_uninstall() {
// Delete node type variables.
......@@ -473,7 +476,6 @@ function node_uninstall() {
}
// Delete node search ranking variables.
// @see node_ranking(), _node_rankings()
variable_del('node_rank_relevance');
variable_del('node_rank_sticky');
variable_del('node_rank_promote');
......
......@@ -287,6 +287,9 @@ function node_field_display_node_alter(&$display, $context) {
*
* @param Drupal\node\Node $node
* A node entity.
*
* @return array
* An array with 'path' as the key and Node ID as its value.
*/
function node_uri(Node $node) {
return array(
......@@ -360,6 +363,13 @@ function node_tag_new(Node $node) {
/**
* Retrieves the timestamp for the current user's last view of a specified node.
*
* @param int $nid
* A node ID.
*
* @return int
* If a node has been previously viewed by the user, the timestamp in seconds
* of when the last view occurred; otherwise, zero.
*/
function node_last_viewed($nid) {
global $user;
......@@ -411,6 +421,7 @@ function node_mark($nid, $timestamp) {
* @return
* An array of node types, as objects, keyed by the type.
*
* @see _node_types_build()
* @see node_type_load()
*/
function node_type_get_types() {
......@@ -445,6 +456,8 @@ function node_type_get_base($type) {
*
* @return
* An array of node type labels, keyed by the node type name.
*
* @see _node_types_build()
*/
function node_type_get_names() {
return _node_types_build()->names;
......@@ -784,7 +797,8 @@ function node_type_update_nodes($old_type, $type) {
* until node_types_rebuild() is called.
*
* @param $rebuild
* TRUE to rebuild node types. Equivalent to calling node_types_rebuild().
* (optional) TRUE to rebuild node types. Equivalent to calling
* node_types_rebuild(). Defaults to FALSE.
*
* @return
* An object with two properties:
......@@ -897,6 +911,8 @@ function node_type_cache_reset() {
*
* @return
* A node type object, with missing values in $info set to their defaults.
*
* @see hook_node_ifo()
*/
function node_type_set_defaults($info = array()) {
$info = (array) $info;
......@@ -999,7 +1015,8 @@ function node_hook($type, $hook) {
* @param $hook
* A string containing the name of the hook.
* @param $a2, $a3, $a4
* Arguments to pass on to the hook, after the $node argument.
* (optional) Arguments to pass on to the hook, after the $node argument. All
* default to NULL.
*
* @return
* The returned value of the invoked hook.
......@@ -1020,7 +1037,8 @@ function node_invoke($node, $hook, $a2 = NULL, $a3 = NULL, $a4 = NULL) {
* @param array $nids
* (optional) An array of entity IDs. If omitted, all entities are loaded.
* @param bool $reset
* (optional) Whether to reset the internal node_load() cache.
* (optional) Whether to reset the internal node_load() cache. Defaults to
* FALSE.
*
* @return array
* An array of node entities indexed by nid.
......@@ -1038,7 +1056,8 @@ function node_load_multiple(array $nids = NULL, $reset = FALSE) {
* @param int $nid
* The node ID.
* @param bool $reset
* (optional) Whether to reset the node_load_multiple() cache.
* (optional) Whether to reset the node_load_multiple() cache. Defaults to
* FALSE.
*
* @return Drupal\node\Node|false
* A fully-populated node entity, or FALSE if the node is not found.
......@@ -1062,6 +1081,12 @@ function node_revision_load($vid = NULL) {
/**
* Prepares a node for saving by populating the author and creation date.
*
* @param object $node
* A node object.
*
* @return object
* An updated node object.
*/
function node_submit($node) {
global $user;
......@@ -1129,7 +1154,7 @@ function node_delete_multiple($nids) {
* The revision ID to delete.
*
* @return
* TRUE if the revision deletion was successful.
* TRUE if the revision deletion was successful; otherwise, FALSE.
*/
function node_revision_delete($revision_id) {
if ($revision = node_revision_load($revision_id)) {
......@@ -1295,7 +1320,7 @@ function node_build_content(Node $node, $view_mode = 'full', $langcode = NULL) {
* A node entity.
* @param $message
* (optional) A flag which sets a page title relevant to the revision being
* viewed.
* viewed. Default is FALSE.
*
* @return
* A $page element suitable for use by drupal_render().
......@@ -1764,10 +1789,11 @@ function theme_node_search_admin($variables) {
* @param object $account
* (optional) A user object representing the user for whom the operation is
* to be performed. Determines access for a user other than the current user.
* Defaults to NULL.
* @param $langcode
* (optional) Language code for the variant of the node. Different language
* variants might have different permissions associated. If NULL, the
* original langcode of the node is used.
* original langcode of the node is used. Defaults to NULL.
*
* @return
* TRUE if the operation may be performed, FALSE otherwise.
......@@ -2050,6 +2076,9 @@ function node_menu_local_tasks_alter(&$data, $router_item, $root_path) {
* @param $type
* The node type object.
*
* @return string
* An unsanitized string that is the title of the node type edit form.
*
* @see node_menu()
*/
function node_type_page_title($type) {
......@@ -2062,6 +2091,9 @@ function node_type_page_title($type) {
* @param Drupal\node\Node $node
* The node entity.
*
* @return
* An unsanitized string that is the title of the node.
*
* @see node_menu()
*/
function node_page_title(Node $node) {
......@@ -2086,6 +2118,9 @@ function node_last_changed($nid) {
*
* @param Drupal\node\Node $node
* The node entity.
*
* @return
* An associative array keyed by node revision number.
*/
function node_revision_list(Node $node) {
$revisions = array();
......@@ -2440,6 +2475,9 @@ function node_block_list_alter(&$blocks) {
* @link http://cyber.law.harvard.edu/rss/rss.html RSS 2.0 Specification. @endlink
* The link should be an absolute URL.
*
* @return Symfony\Component\HttpFoundation\Response
* A response object.
*
* @see node_menu()
*/
function node_feed($nids = FALSE, $channel = array()) {
......@@ -2545,6 +2583,9 @@ function node_view_multiple($nodes, $view_mode = 'teaser', $weight = 0, $langcod
/**
* Page callback: Generates a listing of promoted nodes.
*
* @return array
* An array in the format expected by drupal_render().
*
* @see node_menu()
*/
function node_page_default() {
......@@ -2601,6 +2642,9 @@ function node_page_default() {
* @param Drupal\node\Node $node
* The node entity.
*
* @return
* A page array suitable for use by drupal_render().
*
* @see node_menu()
*/
function node_page_view(Node $node) {
......@@ -2908,10 +2952,11 @@ function node_form_system_themes_admin_form_submit($form, &$form_state) {
* @param $account
* (optional) A user object representing the user for whom the operation is to
* be performed. Determines access for a user other than the current user.
* Defaults to NULL.
* @param $langcode
* (optional) Language code for the variant of the node. Different language
* variants might have different permissions associated. If NULL, the
* original langcode of the node is used.
* original langcode of the node is used. Defaults to NULL.
*
* @return
* TRUE if the operation may be performed, FALSE otherwise.
......@@ -3123,7 +3168,7 @@ function node_permissions_get_configured_types() {
* The operation that the user is trying to perform.
* @param $account
* (optional) The user object for the user performing the operation. If
* omitted, the current user is used.
* omitted, the current user is used. Defaults to NULL.
*
* @return
* An associative array in which the keys are realms, and the values are
......@@ -3157,7 +3202,7 @@ function node_access_grants($op, $account = NULL) {
*
* @param $account
* (optional) The user object for the user whose access is being checked. If
* omitted, the current user is used.
* omitted, the current user is used. Defaults to NULL.
*
* @return
* TRUE if 'view' access to all nodes is granted, FALSE otherwise.
......@@ -3242,6 +3287,9 @@ function node_query_entity_field_access_alter(AlterableInterface $query) {
* Either 'node' or 'entity' depending on what sort of query it is. See
* node_query_node_access_alter() and node_query_entity_field_access_alter()
* for more.
*
* @see node_query_node_access_alter()
* @see node_query_entity_field_access_alter()
*/
function _node_query_node_access_alter($query, $type) {
global $user;
......@@ -3420,11 +3468,12 @@ function node_access_acquire_grants(Node $node, $delete = TRUE) {
* is a module-defined id to define grant privileges. each grant_* field
* is a boolean value.
* @param $realm
* (optional) If provided, read/write grants for that realm only.
* (optional) If provided, read/write grants for that realm only. Defaults to
* NULL.
* @param $delete
* (optional) If false, does not delete records. This is only for optimization
* purposes, and assumes the caller has already performed a mass delete of
* some form.
* some form. Defaults to TRUE.
*/
function _node_access_write_grants(Node $node, $grants, $realm = NULL, $delete = TRUE) {
if ($delete) {
......@@ -3499,7 +3548,8 @@ function node_access_needs_rebuild($rebuild = NULL) {
* has a large number of nodes). hook_update_N() and any form submit handler
* are safe contexts to use the 'batch mode'. Less decidable cases (such as
* calls from hook_user(), hook_taxonomy(), etc.) might consider using the
* non-batch mode.
* non-batch mode. Defaults to FALSE.
*
* @see node_access_needs_rebuild()
*/
function node_access_rebuild($batch_mode = FALSE) {
......@@ -3559,6 +3609,9 @@ function node_access_rebuild($batch_mode = FALSE) {
* This is a multistep operation : we go through all nodes by packs of 20.
* The batch processing engine interrupts processing and sends progress
* feedback after 1 second execution time.
*
* @param array $context
* An array of contextual key/value information for rebuild batch process.
*/
function _node_access_rebuild_batch_operation(&$context) {
if (empty($context['sandbox'])) {
......@@ -3590,6 +3643,13 @@ function _node_access_rebuild_batch_operation(&$context) {
/**
* Post-processing for node_access_rebuild_batch.
*
* @param bool $success
* A boolean indicating whether the re-build process has completed.
* @param array $results
* An array of results information.
* @param array $operations
* An array of function calls (not used in this function).
*/
function _node_access_rebuild_batch_finished($success, $results, $operations) {
if ($success) {
......@@ -3913,6 +3973,12 @@ function node_assign_owner_action_submit($form, $form_state) {
/**
* Generates settings form for node_unpublish_by_keyword_action().
*
* @param array $context
* Array of additional information about what triggered this action.
*
* @return array
* A form array.
*/
function node_unpublish_by_keyword_action_form($context) {
$form['keywords'] = array(
......
......@@ -14,6 +14,12 @@
/**
* Page callback: Presents the node editing form.
*
* @param object $node
* A node object.
*
* @return array
* A form array as expected by drupal_render().
*
* @see node_menu()
*/
function node_page_edit($node) {
......@@ -26,6 +32,11 @@ function node_page_edit($node) {
*
* Redirects to node/add/[type] if only one content type is available.
*
* @return array
* A render array for a list of the node types that can be added; however, if
* there is only one node type defined for the site, the function redirects
* to the node add page for that one node type and does not return at all.
*
* @see node_menu()
*/
function node_add_page() {
......@@ -51,7 +62,11 @@ function node_add_page() {
* An associative array containing:
* - content: An array of content types.
*
* @return string
* An HTML-formatted string.
*
* @see node_add_page()
*
* @ingroup themeable
*/
function theme_node_add_list($variables) {
......@@ -79,8 +94,8 @@ function theme_node_add_list($variables) {
* @param $node_type
* The node type object for the submitted node.
*
* @return
* Returns a node submission form.
* @return array
* A node submission form.
*
* @see node_menu()
*/
......@@ -107,7 +122,7 @@ function node_add($node_type) {
* The node to preview.
*
* @return
* Themed node preview.
* An HTML-formatted string of a node preview.
*
* @see node_form_build_preview()
*/
......@@ -155,6 +170,7 @@ function node_preview(Node $node) {
* - node: The node entity which is being previewed.
*
* @see NodeFormController::preview()
*
* @ingroup themeable
*/
function theme_node_preview($variables) {
......@@ -187,6 +203,12 @@ function theme_node_preview($variables) {
/**
* Page callback: Form constructor for node deletion confirmation form.
*
* @param object $node
* A node object.
*
* @return array
* A form array.
*
* @see node_menu()
*/
function node_delete_confirm($form, &$form_state, $node) {
......@@ -218,6 +240,12 @@ function node_delete_confirm_submit($form, &$form_state) {
/**
* Page callback: Generates an overview table of older revisions of a node.
*
* @param object $node
* A node object.
*
* @return array
* An array as expected by drupal_render().
*
* @see node_menu()
*/
function node_revision_overview($node) {
......@@ -276,6 +304,12 @@ function node_revision_overview($node) {
*
* This form prevents against CSRF attacks.
*
* @param int $node_revision
* The node revision ID.
*
* @return array
* An array as expected by drupal_render().
*
* @see node_menu()
* @see node_revision_revert_confirm_submit()
*/
......@@ -311,6 +345,12 @@ function node_revision_revert_confirm_submit($form, &$form_state) {
*
* This form prevents against CSRF attacks.
*
* @param $node_revision
* The node revision ID.
*
* @return
* An array as expected by drupal_render().
*
* @see node_menu()
* @see node_revision_delete_confirm_submit()
*/
......
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