Eslint-plugin-jsdoc: require-description-complete-sentence heuristic for detecting incomplete sentences via capitalization is broken.

[Elberet]

The require-description-complete-sentence rule assumes that capital letters always indicate the start of a sentence. This heuristic fails whenever a description contains a capitalized word that appears at the beginning of a line, for example due to line wrapping:

/**
 * Implements support for the
 * Swahili voice synthesizer.
 */
function speak() { ... }

This causes a conflict between the linter rule and natural language grammar rules which require certain words to always be capitalized - e.g. above: proper nouns (names of people, countries, languages, nationalities) must always be capitalized in English.

I would suggest to add an option to the require-description-complete-sentence rule to selective enable or disable the capital letter heuristic.

[prometheas]

I'm running into this a lot, myself.

[brettz9]

I've added PR #548 to attempt to implement this suggested config to disable this kind of reporting.

FWIW, the three errors specific to the rule that are currently reported:

1. "Sentence should start with an uppercase character."
2. "Sentence must end with a period."
3. "A line of text is started with an uppercase character, but preceding line does not end the sentence."

The new proposed option newlineBeforeCapsAssumesBadSentenceEnd if set to false can disable no. 3.

Note that the proposed wording is more verbose than just say newlineAssumesSentenceEnd because this proposed change will still not cause no. 2 to be reported for this (as it should if we were to always treat a line break as a sentence end):

/**
 * Here is a long
 * description.
*/

I have not set the default to false as I think may be a safer option. Let me know if the consensus is to make a somewhat breaking change to default to false instead of keeping the existing behavior.

[Elberet]

I believe the proposed change would solve the issue, but the option name is really, really verbose...

Per the current docs:

• Every line in a paragraph (except the first) which starts with an uppercase character must be preceded by a line ending with a period.

The new option modifies this behaviour, so the option name should reflect this specifically, but I have no idea how to condense this into a two-to-four word option name...

Regarding changing the default setting, I believe that changing the default to false is warranted and should be handled as a breaking change that corrects a wart. The current behaviour is founded on wrong assumptions regarding natural language in the default use-case. And the typical solution to corrent an offending description text would be to reword the sentence or insert useless words to manipulate line-breaks, thus defeating the goal of promoting clear, concise, human-readable documentation.

[prometheas]

The trouble really is that this is a very half-baked assertion:

Every line in a paragraph (except the first) which starts with an uppercase character must be preceded by a line ending with a period.

It's patently untrue (and especially obvious to those of us who are old enough to have grown up with typewriters, but now I'm dating myself… 😅); sentences don't give a fig about the number of columns available to the author—they will unfold exactly as needed for communication to succeed 😉

Also, proper nouns (class names, etc) and acronyms are common AF in software development, and can land literally _anywhere_ in sentences, line wraps be damned.

So, if anything, that guidance should arguably be stricken entirely from canon, IMO.

Honestly, it seems a bit crazy to delve into grammatical validation without using some sort of actual grammatical analysis engine for that feedback (write-good, gramma, etc)… bad grammar validation from tooling is _worse than_ no grammar validation at all, given how likely a false recommendation is to occur.

It may even make sense to punt description text to a Markdown linter, not unlike how sample code in docblocks can be handed over to JS linting.

But, in the spirit of trying to fix the current problem in the simplest manner, and without adding dependencies, I believe that the following fine-tuning will yield improved results:

1. The very first character in a description should be capitalized (if it is a letter).
2. The very first character after an empty line (which should be used to separate paragraphs in readable doc blocks) should be capitalized.
3. A sentence that has an empty line after it should end in terminal punctuation (period, question mark, exclamation, and whatever else is common in the written language).

[brettz9]

@Elberet : Yes, I didn't like how verbose it was either, but I believe it is usually better to err on the side of semantic accuracy for any reading or use of the option rather than by being too obscure.

@prometheas and @Elberet : Yes, naturally there are all kinds of nuances in parsing syntax, and I don't think there was a lack of awareness of this when the rule was created.

I looked at adding dedicated English parsers (a few on npm) myself previously, but they just weren't good enough. I haven't closely investigated the ones you mentioned, though:

1. As you say, @prometheas , it would be another dependency
2. write-good's checks don't seem to do sentence parsing and gramma looks heavy (using a server).

A Markdown linter, assuming it parsed sentences, would also bring up concerns that it is adding code specific to one language that is not even blessed by jsdoc (though there is a plugin for it).

I think the rule currently follows the 3 rules you mention, though correct me if I'm wrong. It sounds like there is agreement to stop making the new line capitalization behavior (with "newline" meaning a single line break as opposed to 2 line breaks) applicable by default.

It is not high on my priority list to do much with this rule, but it is easy enough to apply the PR which makes its use optional. Note that some may be attentive enough to note that when they
make a line break, it will be interpreted as a new sentence, so for such users, the option may still be useful to apply. It is for such users I think we shouldn't drop the behavior entirely, but disable by default. (It's frustrating enough if the default changes, but worse if the whole behavior one has relied on has been removed.)

[brettz9]

The PR to make the behavior optional is ready. Who thinks we should:

1. Drop the option entirely
2. Keep the option but change so it is not the default.
3. (If anyone wants to keep the option as is, keeping it the default.)

[prometheas]

Well. I myself feel like you made an excellent point about keeping existing linting configs working. I think off is the best default, but perhaps make that the default at the next major bump?

Though I suppose you could just as easily major bump now…

[raineorshine]

I vote for 2

[gajus]

:tada: This issue has been resolved in version 26.0.0 :tada:

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot :package::rocket: