Improve inline docs for check_comment()

[DrewAPicture]

Need to do:

• Remove duplication of the 'number of links' phrase in the function docblock
• Format params
• Add the alternative return of false to the @return tag
• Fix various inline comment syntax

[DrewAPicture]

Main docblock fixes

[DrewAPicture]

Inline comment fixes

[DrewAPicture]

In 29762:

Improve documentation in the check_comments() docblock.

• Removes two duplicate sentences from the long description
• Tightens up phrasing elsewhere in the long description for specific checks
• Clarifies the parameter and return descriptions, and adds periods

See #29734.

[DrewAPicture]

In 29763:

Improve and clarify inline commenting inside the check_comment() function.

Adds logical explanations of what some of the various comment checks are checking for, as well as some general cleanup and syntax fixes.

Fixes #29734.