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

Describe the problem you have found:

Field widget form elements should be based on the passed in $element...

Probably should be:

Field widget form elements should be based on the given $element...

Otherwise the first parse is "Form elements for field widgets should be based on the (missing word: data? array? kittycat?) which is passed in the $element argument...".

CommentFileSizeAuthor
#9 hook_field_widget_punctuation_error-1066118-8.patch11.02 KBbarrett
#7 hook_field_widget_punctuation_error-1066118.patch11.7 KBbarrett

Comments

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented
Status: Active » Postponed (maintainer needs more info)

Um. I'm not seeing a documentation problem here, except that technically passed-in should have a hyphen in the middle of it. Can you explain why you think the current wording is a problem? We often use parameter variable names in docblocks, as it's clearer than trying to guess which parameter something is referring to, in my opinion at least.

robertb-1’s picture

robertb-1 commented

Well, either "given" or "passed-in" is fine. I come from Java, where "given" is used all over the place. Adding a hyphen would resolve the problem. When I read the sentence initially, I assumed "in" introduced a prepositional phrase, with $element as its argument. That clearly didn't allow the sentence to parse, so I had to back-track until I found the syntax error ("passed in" should be "passed-in"). One little hyphen prevents an entire cloud of question marks above one's head :)

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented
Title: Documentation problem with hook_field_widget_form » hook_field_widget_form has punctuation error
Priority: Normal » Minor
Status: Postponed (maintainer needs more info) » Active
Issue tags: +Novice

ok, then we just need a hyphen and everyone will be happy. Good project in patch making for a novice contributor to Drupal...

bfroehle’s picture

bfroehle commented
Title: hook_field_widget_form has punctuation error » hook_field_widget_form() has punctuation error

Just FYI: "passed in" is used all over in Drupal

$ find * -type f -print0 | xargs -0 egrep "passed in \\$"
includes/common.inc: *   - #query: The passed in $query.
includes/graph.inc: *   The passed in $graph with more secondary keys filled in:
includes/theme.inc: *   - 'type': The passed in $type.
includes/theme.inc: *   - 'theme path': The passed in $path.
modules/field/field.api.php: * Field widget form elements should be based on the passed in $element, which
modules/system/system.api.php: * access. The passed in $router_item is statically cached for the current request, so this
jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented

They should all have hyphens. The rule is that if you put 2 or more words together to form an adjective, they need to be hyphenated, and all of those examples are like that.

barrett’s picture

barrett commented
Assigned: Unassigned » barrett
barrett’s picture

barrett commented
Status: Active » Needs review
StatusFileSize
new hook_field_widget_punctuation_error-1066118.patch11.7 KB
jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented
Status: Needs review » Needs work

Most of these are good, but a few exceptions:

a) The capitalization should not have been changed here:

- * - Passed into the other block hooks in your module as an argument to
+ * - passed in to the other block hooks in your module as an argument to

See http://drupal.org/node/1354#lists

Also I think in this case that "passed into" is fine? This sentence is saying what happens, as in "This is passed into another function".

b)

-  // We return exactly what was passed in, to guarantee that the page will
+  // We return exactly what was passed-in, to guarantee that the page will

This one is not a compound being used as an adjective -- "passed" is a verb here. No hyphen. There are several other places in this patch that have the same problem.

barrett’s picture

barrett commented
Status: Needs work » Needs review
StatusFileSize
new hook_field_widget_punctuation_error-1066118-8.patch11.02 KB

Do you hear a weird, cackling noise? That's my eighth-grade English teacher mocking me for not having paid more attention to her.

I think I have it corrected now.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented
Version: 7.x-dev » 8.x-dev
Status: Needs review » Reviewed & tested by the community
Issue tags: +Quick fix

That looks better. Thanks! Should be committed to 8.x and 7.x.

dries’s picture

dries commented
Status: Reviewed & tested by the community » Fixed

Committed to 7.x and 8.x.

Status: Fixed » Closed (fixed)
Issue tags: -Quick fix, -Novice

Automatically closed -- issue fixed for 2 weeks with no activity.

Issue tags: +Quick fix, +Novice

Restoring issue tags, see #2125755: System messages removed all issue tags during D7 upgrade.