API page: http://api.drupal.org/api/drupal/modules%21system%21system.api.php/funct...
The whole of a hook_update_N() implementation's docblock is shown to the user in the update.php UI. (At least IIRC it's the whole of it, badly formatted if there's more than one line so should probably mention to keep it to a single line, and it's a wacky magic feature, but let's pass on that for now ;)
The info in this comment should be folded into the docs: http://api.drupal.org/comment/16914#comment-16914
