Message:

@param and @return descriptions begin indented on the next line. (Drupal Docs)	Other	linkchecker.module	700	N/A

/**
 * Add node links to database.
 *
 * @param object $node
 *   The fully populated node object.
 * @param bool $skip_missing_links_detection
 *   To prevent endless batch loops the value need to be TRUE. With FALSE
 *   the need for content re-scans is detected by the number of missing links.
 */

Line 700:

 * @param object $node

What should this tell me? I see nothing wrong. Indention looks correct...

Found in automated testing.

CommentFileSizeAuthor
#8 object_type.patch728 bytesaspilicious
#3 ctl-1390040.patch553 bytesxjm

Comments

hass’s picture

hass commented
Project: Coder » Coder Tough Love
Version: 7.x-1.x-dev » 6.x-1.x-dev
xjm’s picture

xjm
she/her
Primary language English
commented

Looks like the additional bug @Dane Powell found in #1361528-4: Remove "@param and @return syntax does not indicate the data type" rule.

xjm’s picture

xjm
she/her
Primary language English
commented
Priority: Major » Normal
Status: Active » Needs review
StatusFileSize
new ctl-1390040.patch553 bytes

I believe the attached patch should resolve this.

tim.plunkett’s picture

tim.plunkett
he/him
Primary language English
Location Philadelphia
commented
Status: Needs review » Reviewed & tested by the community

This looks fine to me. Just give it a better commit message than the issue title please :)

xjm’s picture

xjm
she/her
Primary language English
commented
Title: @param and @return descriptions begin indented on the next line. » 'object' datatype is not matched in API docs, triggering '@param and @return descriptions begin indented on the next line'
xjm’s picture

xjm
she/her
Primary language English
commented
Status: Reviewed & tested by the community » Fixed

Fixed in 6.x-1.x and 7.x-1.x:
http://drupal.org/commitlog/commit/7948/effe57f9246e9a5c19043d03d2e7bda0...
http://drupal.org/commitlog/commit/7948/8abe413d36cd7a4bf950e1a371ae36aa...

aspilicious’s picture

aspilicious commented
Title: 'object' datatype is not matched in API docs, triggering '@param and @return descriptions begin indented on the next line' » 'bool, ...' datatype is not matched in API docs, triggering '@param and @return descriptions begin indented on the next line'
Status: Fixed » Needs review
StatusFileSize
new object_type.patch728 bytes

We alse need to add: bool, float, double, real

hass’s picture

hass commented

null is missing, see http://drupal.org/node/1354#functions and piped types also...

hass’s picture

hass commented
Status: Needs review » Needs work
xjm’s picture

xjm
she/her
Primary language English
commented
Title: 'bool, ...' datatype is not matched in API docs, triggering '@param and @return descriptions begin indented on the next line' » several datatypes are not matched in API docs, triggering '@param and @return descriptions begin indented on the next line'

@aspilicious and I talked about this a bit in IRC. We need to match:

  • One word only, or a string of words concatenated with |.
  • Types in the patch.
  • NULL, TRUE, and FALSE. Sorry, they need to be lowercase. null, true, false. That always trips me up.
  • Arbitrary class names.

So, I'm wondering if we should rewrite the rule to simply skip the whitelist and instead match the line. Split it into two rules, one for param and one for return. The param rule allows:

  • @param $var
  • @param foo $var
  • @param foo|bar $var

The return rule allows:

  • @return
  • @return foo
  • @return foo|bar

And we change the message text a little to not have the somewhat confusing text about description.

Separate rules would do some checking on the datatypes and make sure that the true, false, and null are lowercase; that true and false are not piped together; etc. (See specifics in http://drupal.org/node/1354#functions).

The above rules are also candidates for inclusion in Coder.

For now, though, I'm going to commit #8 to reduce false positive noise on the bots.

P.S. A potential CTL rule might flag the code smell from having too many different datatypes piped together.

aspilicious’s picture

aspilicious commented

The docs say you should only pipe once.
And mixed should be replaced with pipes

xjm’s picture

xjm
she/her
Primary language English
commented

Ah, want to reroll to take out mixed, then?

xjm’s picture

xjm
she/her
Primary language English
commented

Hmm, I saw mixed used in the CMI patch. Maybe taking that out needs more discussion.

For now I committed #8:
http://drupal.org/commitlog/commit/7948/0e7162622da464473382d58418e16c1c...
http://drupal.org/commitlog/commit/7948/a5779aa98478d3d894b543a891880ee0...

Leaving this issue open to look at a better solution like the one outlined above.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented

FYI, probably covered by above comments, but I'm seeing this false positive on the first line here:

 * @param PGPBody $statements
 *   A PGPBody object containing body statements.