hook_node_submit doc is not quite correct

API page: http://api.drupal.org/api/drupal/modules--node--node.api.php/function/ho...

Describe the problem you have found:

The signature for hook_node_submit is not consistent with expected behavior. According to the comment in function node_form_submit_build_node:

  // @todo Legacy support for modules that extend the node form with form-level
  //   submit handlers that adjust $form_state['values'] prior to those values
  //   being used to update the entity. Module authors are encouraged to instead
  //   adjust the node directly within a hook_node_submit() implementation. For
  //   Drupal 8, evaluate whether the pattern of triggering form-level submit
  //   handlers during button-level submit processing is worth supporting
  //   properly, and if so, add a Form API function for doing so.

Note that "Module authors are encouraged to instead adjust the node directly within hook_node_submit...". However, according to the documentation the signature for hook_node_submit takes $node as a copy and not a reference. Functionally, module implementors can simply supply the hook with node as a reference (e.g. hook_node_submit(&$node...) and indeed modify the node as necessary.

Reco: Add the '&' in front of the $node parameter in the signature in the documentation.