API documentation for function "theme_comment_view" needs clarification/expanding

Really? What explanation do you think is actually needed?

My opinion: The theme function doesn't really need to know much about the links, except that it should print them out, and the implementation of the function shows you the default way to print them out (via theme('comment')) so I would tend to leave this as it is.

If you can explain why you need more information or what you'd suggest putting in there, I'd be willing to change my mind...

http://api.drupal.org/api/function/theme_comment_view/6

OK...

Here's what I think it should say:

@param $links
An associative array containing link information suitable for passing into theme_links(), generated by modules implementing hook_link() with $type='comment'. Typically these are command links for editing, deleting, and other operations on the comment.

Other notes to whoever decides to patch this:
- The one-line description at the beginning of this function doc uses the word "block", but it doesn't mean a block in the sense of the Block module, so it should probably be changed to remove that word.
- The $visible parameter should be more explicit (TRUE if comments are visible, FALSE if they are in "folded" view.)

Good project for a new API doc/Drupal contributor. :)

Patch file is attached.

That's a good start, thanks!

A few problems with this patch:

a) It doesn't apply at the top level of the Drupal repo. You should always do patches from the perspective of the top level of Drupal.

b)

   * @param $links
   *   An associative array containing control links.
+  *   Suitable for passing into theme_links()
+  *   Generated by modules implementing hook_link() with $type='comment'
+  *   Example: Edit Comment, Delete Comment, etc...

Please wrap all lines in documentation blocks at as close to 80 characters as possible (without going over 80 characters). Sentences should end with ".", and non-sentences should be made into sentences.

Also, the links in Drupal generally are all lower case, or sentence case. So they might be "edit comment" or "Edit comment", but they are unlikely to say "Edit Comment".

I would suggest avoiding specifics of the wording of the links, anyway, and instead describe them, like "such as links for editing, deleting, and replying to a comment".

c) The patch doesn't address all the comments/suggestions in #3 above.

Made the requested changes. This time around I also worked in this:

- The $visible parameter should be more explicit (TRUE if comments are visible, FALSE if they are in "folded" view.)

Looks good -- almost there... Just one minor problem:

The first line of a function doc should start with a verb in 3rd person, such as "Themes the", rather than "Theme the". See http://drupal.org/node/1354 for reference.

I'll be getting to it tonight.

With changes specified by jhodgdon. Added the letter 's' to the word 'theme' in the initial description.

forgot to switch to needs review

Spaces at end of two lines...

Spaces removed.

Good work, let's get this in.

Thanks, committed.

BTW checked it does not apply to Drupal 7 due to no such function being there.