Commit 7a434fd9 authored by catch's avatar catch

Issue #1313980 by jn2: Clean up API docs for node module.

parent ca250782
......@@ -6,7 +6,11 @@
*/
/**
* Displays the content type admin overview page.
* Page callback: Displays the content type admin overview page.
*
* Path: admin/structure/types
*
* @see node_menu()
*/
function node_overview_types() {
$types = node_type_get_types();
......@@ -54,7 +58,7 @@ function node_overview_types() {
}
/**
* Returns HTML for a node type description for the content type admin overview page.
* Returns HTML for a node type description for the content type admin page.
*
* @param $variables
* An associative array containing:
......@@ -409,7 +413,17 @@ function node_type_reset($type) {
}
/**
* Menu callback; delete a single content type.
* Page callback: Form constructor for the content type delete form.
*
* Path: admin/structure/types/manage/%node_type/delete
*
* @param $type
* Content type object.
*
* @return
* Form array for delete confirmation form.
*
* @see node_type_delete_confirm_submit()
*/
function node_type_delete_confirm($form, &$form_state, $type) {
$form['type'] = array('#type' => 'value', '#value' => $type->type);
......@@ -429,7 +443,7 @@ function node_type_delete_confirm($form, &$form_state, $type) {
}
/**
* Process content type delete confirm submissions.
* Form submission handler for node_type_delete_confirm().
*/
function node_type_delete_confirm_submit($form, &$form_state) {
node_type_delete($form_state['values']['type']);
......
......@@ -6,7 +6,12 @@
*/
/**
* Menu callback: confirm rebuilding of permissions.
* Page callback: Form constructor for the permission rebuild confirmation form.
*
* Path: admin/reports/status/rebuild
*
* @see node_menu()
* @see node_configure_rebuild_confirm_submit()
*/
function node_configure_rebuild_confirm() {
return confirm_form(array(), t('Are you sure you want to rebuild the permissions on site content?'),
......@@ -14,7 +19,7 @@ function node_configure_rebuild_confirm() {
}
/**
* Handler for wipe confirmation
* Form submission handler for node_configure_rebuild_confirm().
*/
function node_configure_rebuild_confirm_submit($form, &$form_state) {
node_access_rebuild(TRUE);
......@@ -65,7 +70,10 @@ function node_node_operations() {
}
/**
* List node administration filters that can be applied.
* Lists node administration filters that can be applied.
*
* @return
* Associative array of filters.
*/
function node_filters() {
// Regular filters
......@@ -110,7 +118,7 @@ function node_filters() {
}
/**
* Apply filters for node administration filters based on session.
* Applies filters for the node administration overview based on session.
*
* @param $query
* A SelectQuery to which the filters should be applied.
......@@ -133,7 +141,15 @@ function node_build_filter_query(SelectQueryInterface $query) {
}
/**
* Return form for node administration filters.
* Returns the node administration filters form object 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()
* @ingroup forms
*/
function node_filter_form() {
$session = isset($_SESSION['node_overview_filter']) ? $_SESSION['node_overview_filter'] : array();
......@@ -208,7 +224,15 @@ function node_filter_form() {
}
/**
* Process result from node administration 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()
*/
function node_filter_form_submit($form, &$form_state) {
$filters = node_filters();
......@@ -237,18 +261,19 @@ function node_filter_form_submit($form, &$form_state) {
}
/**
* Make mass update of nodes, changing all nodes in the $nodes array
* to update them with the field values in $updates.
* Updates all nodes in the passed-in array with the passed-in field values.
*
* IMPORTANT NOTE: This function is intended to work when called
* from a form submit handler. Calling it outside of the form submission
* from a form submission handler. Calling it outside of the form submission
* process may not work correctly.
*
* @param array $nodes
* Array of node nids to update.
* @param array $updates
* Array of key/value pairs with node field names and the
* value to update that field to.
* Array of key/value pairs with node field names and the value to update
* that field to.
*
* @ingroup batch
*/
function node_mass_update($nodes, $updates) {
// We use batch processing to prevent timeout when updating a large number
......@@ -279,7 +304,14 @@ function node_mass_update($nodes, $updates) {
}
/**
* Node Mass Update - helper function.
* Updates individual nodes when fewer than 10 are queued.
*
* @param $nid
* ID of node to update.
* @param $updates
* Associative array of updates.
*
* @see node_mass_update()
*/
function _node_mass_update_helper($nid, $updates) {
$node = node_load($nid, NULL, TRUE);
......@@ -293,7 +325,7 @@ function _node_mass_update_helper($nid, $updates) {
}
/**
* Node Mass Update Batch operation
* Executes a batch operation for node_mass_update().
*/
function _node_mass_update_batch_process($nodes, $updates, &$context) {
if (!isset($context['sandbox']['progress'])) {
......@@ -324,7 +356,7 @@ function _node_mass_update_batch_process($nodes, $updates, &$context) {
}
/**
* Node Mass Update Batch 'finished' callback.
* Reports the 'finished' status of batch operation for node_mass_update().
*/
function _node_mass_update_batch_finished($success, $results, $operations) {
if ($success) {
......@@ -339,7 +371,18 @@ function _node_mass_update_batch_finished($success, $results, $operations) {
}
/**
* Menu callback: content administration.
* Page callback: Form constructor for the content administration form.
*
* Path: 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_filter_form_submit()
* @see node_menu()
*/
function node_admin_content($form, $form_state) {
if (isset($form_state['values']['operation']) && $form_state['values']['operation'] == 'delete') {
......@@ -353,7 +396,15 @@ function node_admin_content($form, $form_state) {
}
/**
* Form builder: Builds the node administration overview.
* 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()
* @ingroup forms
*/
function node_admin_nodes() {
$admin_access = user_access('administer nodes');
......@@ -521,10 +572,17 @@ function node_admin_nodes() {
}
/**
* Validate node_admin_nodes form submissions.
* Form validation handler for node_admin_nodes().
*
* Check if any nodes have been selected to perform the chosen
* 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()
*/
function node_admin_nodes_validate($form, &$form_state) {
// Error if there are no items to select.
......@@ -534,9 +592,16 @@ function node_admin_nodes_validate($form, &$form_state) {
}
/**
* Process node_admin_nodes form submissions.
* Form submission handler for node_admin_nodes().
*
* Executes the chosen 'Update option' on the selected nodes.
*
* Execute 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()
*/
function node_admin_nodes_submit($form, &$form_state) {
$operations = module_invoke_all('node_operations');
......@@ -562,6 +627,16 @@ 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()
*/
function node_multiple_delete_confirm($form, &$form_state, $nodes) {
$form['nodes'] = array('#prefix' => '<ul>', '#suffix' => '</ul>', '#tree' => TRUE);
// array_filter returns only elements with TRUE values
......@@ -585,6 +660,16 @@ function node_multiple_delete_confirm($form, &$form_state, $nodes) {
t('Delete'), t('Cancel'));
}
/**
* 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()
*/
function node_multiple_delete_confirm_submit($form, &$form_state) {
if ($form_state['values']['confirm']) {
node_delete_multiple(array_keys($form_state['values']['nodes']));
......
......@@ -177,9 +177,6 @@
* sure to restore your {node_access} record after node_access_rebuild() is
* called.
*
* @see node_access_view_all_nodes()
* @see node_access_rebuild()
*
* @param $account
* The user object whose grants are requested.
* @param $op
......@@ -191,6 +188,8 @@
*
* For a detailed example, see node_access_example.module.
*
* @see node_access_view_all_nodes()
* @see node_access_rebuild()
* @ingroup node_access
*/
function hook_node_grants($account, $op) {
......@@ -252,14 +251,13 @@ function hook_node_grants($account, $op) {
*
* Note: a deny all grant is not written to the database; denies are implicit.
*
* @see _node_access_write_grants()
*
* @param $node
* The node that has just been saved.
*
* @return
* An array of grants as defined above.
*
* @see _node_access_write_grants()
* @ingroup node_access
*/
function hook_node_access_records($node) {
......@@ -304,8 +302,6 @@ function hook_node_access_records($node) {
* modules to modify the $grants array by reference before it is stored, so
* custom or advanced business logic can be applied.
*
* @see hook_node_access_records()
*
* Upon viewing, editing or deleting a node, hook_node_grants() builds a
* permissions array that is compared against the stored access records. The
* user must have one or more matching permissions in order to complete the
......@@ -313,9 +309,6 @@ function hook_node_access_records($node) {
*
* A module may deny all access to a node by setting $grants to an empty array.
*
* @see hook_node_grants()
* @see hook_node_grants_alter()
*
* @param $grants
* The $grants array returned by hook_node_access_records().
* @param $node
......@@ -325,6 +318,9 @@ function hook_node_access_records($node) {
* access modules with a configurable behavior, as shown in the example with the
* 'is_preview' field.
*
* @see hook_node_access_records()
* @see hook_node_grants()
* @see hook_node_grants_alter()
* @ingroup node_access
*/
function hook_node_access_records_alter(&$grants, $node) {
......@@ -351,15 +347,15 @@ function hook_node_access_records_alter(&$grants, $node) {
* multiple node access modules can be altered or advanced business logic can be
* applied.
*
* @see hook_node_grants()
*
* The resulting grants are then checked against the records stored in the
* {node_access} table to determine if the operation may be completed.
*
* A module may deny all access to a user by setting $grants to an empty array.
*
* @see hook_node_access_records()
* @see hook_node_access_records_alter()
* Developers may use this hook to either add additional grants to a user
* or to remove existing grants. These rules are typically based on either the
* permissions assigned to a user role, or specific attributes of a user
* account.
*
* @param $grants
* The $grants array returned by hook_node_grants().
......@@ -368,11 +364,9 @@ function hook_node_access_records_alter(&$grants, $node) {
* @param $op
* The operation being performed, 'view', 'update' or 'delete'.
*
* Developers may use this hook to either add additional grants to a user
* or to remove existing grants. These rules are typically based on either the
* permissions assigned to a user role, or specific attributes of a user
* account.
*
* @see hook_node_grants()
* @see hook_node_access_records()
* @see hook_node_access_records_alter()
* @ingroup node_access
*/
function hook_node_grants_alter(&$grants, $account, $op) {
......@@ -549,7 +543,7 @@ function hook_node_load($nodes, $types) {
}
/**
* Control access to a node.
* Controls access to a node.
*
* Modules may implement this hook if they want to have a say in whether or not
* a given user has access to perform a given operation on a node.
......@@ -785,9 +779,6 @@ function hook_node_submit($node, $form, &$form_state) {
* the RSS item generated for this node.
* For details on how this is used, see node_feed().
*
* @see forum_node_view()
* @see comment_node_view()
*
* @param $node
* The node that is being assembled for rendering.
* @param $view_mode
......@@ -795,6 +786,8 @@ function hook_node_submit($node, $form, &$form_state) {
* @param $langcode
* The language code used for rendering.
*
* @see forum_node_view()
* @see comment_node_view()
* @see hook_entity_view()
*
* @ingroup node_api_hooks
......@@ -1231,8 +1224,9 @@ function hook_validate($node, $form, &$form_state) {
* The node to be displayed, as returned by node_load().
* @param $view_mode
* View mode, e.g. 'full', 'teaser', ...
*
* @return
* $node. The passed $node parameter should be modified as necessary and
* The passed $node parameter should be modified as necessary and
* returned so it can be properly presented. Nodes are prepared for display
* by assembling a structured array, formatted as in the Form API, in
* $node->content. As with Form API arrays, the #weight property can be
......
......@@ -444,7 +444,7 @@ function node_install() {
}
/**
* Utility function: fetch the node types directly from the database.
* Fetches node types directly from the database.
*
* @ingroup update-api-7.x-to-8.x
*/
......
This diff is collapsed.
......@@ -2,12 +2,20 @@
/**
* @file
* Page callbacks for adding, editing, deleting, and revisions management for content.
* Callbacks for adding, editing, and deleting content and managing revisions.
*
* Also includes validation, submission and other helper functions.
*
* @see node_menu()
*/
/**
* Menu callback; presents the node editing form.
* Page callback: Presents the node editing form.
*
* Path: node/%node/edit
*
* @see node_menu()
*/
function node_page_edit($node) {
$type_name = node_type_get_name($node);
......@@ -15,6 +23,13 @@ function node_page_edit($node) {
return drupal_get_form($node->type . '_node_form', $node);
}
/**
* Page callback: Presents the node add form.
*
* Path: node/add
*
* @see node_menu()
*/
function node_add_page() {
$item = menu_get_item();
$content = system_admin_menu_block($item);
......@@ -33,6 +48,7 @@ function node_add_page() {
* An associative array containing:
* - content: An array of content types.
*
* @see node_add_page()
* @ingroup themeable
*/
function theme_node_add_list($variables) {
......@@ -55,7 +71,17 @@ function theme_node_add_list($variables) {
/**
* Returns a node submission form.
* Page callback: Provides the node submission form.
*
* Path: 'node/add/' . $type_url_str (part of a foreach)
*
* @param $type
* The node type for the submitted node.
*
* @return
* Returns a node submission form.
*
* @see node_menu()
*/
function node_add($type) {
global $user;
......@@ -68,6 +94,14 @@ function node_add($type) {
return $output;
}
/**
* Form validation handler for node_form().
*
* @see node_form_delete_submit()
* @see node_form_build_preview()
* @see node_form_submit()
* @see node_form_submit_build_node()
*/
function node_form_validate($form, &$form_state) {
// $form_state['node'] contains the actual entity being edited, but we must
// not update it with form values that have not yet been validated, so we
......@@ -78,7 +112,14 @@ function node_form_validate($form, &$form_state) {
}
/**
* Generate the node add/edit form array.
* Form constructor for the node add/edit form.
*
* @see node_form_delete_submit()
* @see node_form_build_preview()
* @see node_form_validate()
* @see node_form_submit()
* @see node_form_submit_build_node()
* @ingroup forms
*/
function node_form($form, &$form_state, $node) {
global $user;
......@@ -299,7 +340,12 @@ function node_form($form, &$form_state, $node) {
}
/**
* Button submit function: handle the 'Delete' button on the node form.
* Form submission handler for the 'Delete' button for node_form().
*
* @see node_form_build_preview()
* @see node_form_validate()
* @see node_form_submit()
* @see node_form_submit_build_node()
*/
function node_form_delete_submit($form, &$form_state) {
$destination = array();
......@@ -311,7 +357,14 @@ function node_form_delete_submit($form, &$form_state) {
$form_state['redirect'] = array('node/' . $node->nid . '/delete', array('query' => $destination));
}
/**
* Form submission handler for the 'Preview' button for node_form().
*
* @see node_form_delete_submit()
* @see node_form_validate()
* @see node_form_submit()
* @see node_form_submit_build_node()
*/
function node_form_build_preview($form, &$form_state) {
$node = node_form_submit_build_node($form, $form_state);
$form_state['node_preview'] = node_preview($node);
......@@ -319,7 +372,15 @@ function node_form_build_preview($form, &$form_state) {
}
/**
* Generate a node preview.
* Generates a node preview.
*
* @param $node
* The node to preview.
*
* @return
* Themed node preview.
*
* @see node_form_build_preview()
*/
function node_preview($node) {
if (node_access('create', $node) || node_access('update', $node)) {
......@@ -365,6 +426,7 @@ function node_preview($node) {
* An associative array containing:
* - node: The node object which is being previewed.
*
* @see node_preview()
* @ingroup themeable
*/
function theme_node_preview($variables) {
......@@ -395,6 +457,14 @@ function theme_node_preview($variables) {
return $output;
}
/**
* Form submission handler that saves the node for node_form().
*
* @see node_form_delete_submit()
* @see node_form_build_preview()
* @see node_form_validate()
* @see node_form_submit_build_node()
*/
function node_form_submit($form, &$form_state) {
$node = node_form_submit_build_node($form, $form_state);
$insert = empty($node->nid);
......@@ -436,6 +506,10 @@ function node_form_submit($form, &$form_state) {
* before proceeding to the next step.
*
* @see node_form()
* @see node_form_delete_submit()
* @see node_form_build_preview()
* @see node_form_validate()
* @see node_form_submit()
*/
function node_form_submit_build_node($form, &$form_state) {
// @todo Legacy support for modules that extend the node form with form-level
......@@ -460,7 +534,11 @@ function node_form_submit_build_node($form, &$form_state) {
}
/**
* Menu callback -- ask for confirmation of node deletion
* Page callback: Form constructor for node deletion confirmation form.
*
* Path: node/%node/delete
*
* @see node_menu()
*/
function node_delete_confirm($form, &$form_state, $node) {
$form['#node'] = $node;
......@@ -476,7 +554,7 @@ function node_delete_confirm($form, &$form_state, $node) {
}
/**
* Execute node deletion
* Form submission handler for node_delete_confirm().
*/
function node_delete_confirm_submit($form, &$form_state) {
if ($form_state['values']['confirm']) {
......@@ -490,7 +568,11 @@ function node_delete_confirm_submit($form, &$form_state) {
}
/**
* Generate an overview table of older revisions of a node.
* Page callback: Generates an overview table of older revisions of a node.
*
* Path: node/%node/revisions
*
* @see node_menu()
*/
function node_revision_overview($node) {
drupal_set_title(t('Revisions for %title', array('%title' => $node->title)), PASS_THROUGH);
......@@ -541,13 +623,23 @@ function node_revision_overview($node) {
}
/**
* Ask for confirmation of the reversion to prevent against CSRF attacks.
* Page callback: Form constructor for the reversion confirmation form.
*
* Path: node/%node/revisions/%/revert
*
* This form prevents against CSRF attacks.
*
* @see node_menu()
* @see node_revision_revert_confirm_submit()
*/
function node_revision_revert_confirm($form, $form_state, $node_revision) {
<