Issue #1258176 by sven.lauer: API doc for element_children() is only useful...

Issue #1258176 by sven.lauer: API doc for element_children() is only useful for people who already know what 'children' are.

includes/common.inc

@@ -6136,10 +6136,13 @@ function element_child($key) {
 }
 
 /**
- * Return the children of an element, optionally sorted by weight.
+ * Identifies the children of an element array, optionally sorted by weight.
+ *
+ * The children of a element array are those key/value pairs whose key does
+ * not start with a '#'. See drupal_render() for details.
  *
  * @param $elements
- *   The element to be sorted.
+ *   The element array whose children are to be identified.
  * @param $sort
  *   Boolean to indicate whether the children should be sorted by weight.
  * @return

modules/node/node.api.php

@@ -570,25 +570,25 @@ function hook_node_load($nodes, $types) {
  * block access, return NODE_ACCESS_IGNORE or simply return nothing.
  * Blindly returning FALSE will break other node access modules.
  *
- * @link http://api.drupal.org/api/group/node_access/7 More on the node access system @endlink
- * @ingroup node_access
- * @param $node
- *   The node on which the operation is to be performed, or, if it does
- *   not yet exist, the type of node to be created.
- * @param $op
+ * @param object|string $node
+ *   The node on which the operation is to be performed, or a string value
+ *   representing the type of node.
+ * @param string $op
  *   The operation to be performed. Possible values:
  *   - "create"
  *   - "delete"
  *   - "update"
  *   - "view"
- * @param $account
+ * @param object $account
  *   A user object representing the user for whom the operation is to be
  *   performed.
  *
- * @return
+ * @return integer
  *   NODE_ACCESS_ALLOW if the operation is to be allowed;
  *   NODE_ACCESS_DENY if the operation is to be denied;
  *   NODE_ACCESS_IGNORE to not affect this operation at all.
+ *
+ * @ingroup node_access
  */
 function hook_node_access($node, $op, $account) {
   $type = is_string($node) ? $node : $node->type;