Docs: Describe options in rules under Possible Errors part 4

[pedrottimark]

The last rule under Possible Errors

• Make description in h1 consistent with rules index page, not even the first word is capitalized. That is because will soon change the format to match the rules index page (that is, rule-id: rule description).
• Make first sentence under Rule Details consistent with description.
• Add “this rule with” to example sentences.
• Describe options according to patterns in guidelines.

Hint: The diff gets confusing after the bulleted list under Rule Details. At that point, you might click View and compare the markdown view to the Web site: http://eslint.org/docs/rules/valid-jsdoc

@nzakas EDIT can you verify that the rule details are clear, options list is correct, and examples are relevant, because I am just now learning JSDoc
@scriptdaemon your thoughts are welcome, especially on stretching the guidelines, as follows:

So far in new pattern, we describe options in bulleted lists and remove any redundant paragraphs between a level-3 heading for an option and the example code. I am open to your thoughts about including a paragraph of additional info following some of the option headings in this rule doc:

• because this doc has such long scrolling distance from the descriptions to the examples
• because there is some useful information that I cut because it did not fit into the bulleted list

[eslintbot]

LGTM

[mention-bot]

By analyzing the blame information on this pull request, we identified @nzakas, @gyandeeps and @IanVS to be potential reviewers

[scriptdaemon]

I think it would be okay to allow an optional paragraph under option headers when there's important information that won't fit in the list.

Would you agree that adding require-jsdoc as a related rule would be a good idea (this one is already listed as a related rule on the require-jsdoc doc)?

[nzakas]

I'd describe this option as "instead of key use value"

[eslintbot]

LGTM

[nzakas]

Lgtm