require-description-complete-sentence edge conditions

[cscott]

trafficstars

More edge conditions for require-description-complete-sentence:

• [ ] Tries to capitalize after :: https://www.grammarly.com/blog/capitalization-after-colons/
• [ ] Tries to add periods after triple-backquote (instead that region should be protected from capitalization)
• [ ] Tries to add periods after ---

---

Want to back this issue? Post a bounty on it! We accept bounties via Bountysource.

[jugglinmike]

Another edge case: proper nouns

/**
 * This method is defined for backwards compatibility with pre-1.0 releases of
 * Cheerio. Please use [the `load` method exported by the module]{@link
 * module:cheerio.load} instead.
 */

[c-vetter]

Given jsdoc/require-description-complete-sentence and this code:

/**
 * @param {number|string|Date|Object|OverType|WhateverElse} multiType -
 * Nice long explanation...
 */
function test (multiType) {

I get this error:

A line of text is started with an uppercase character, but preceding line does not end the sentence.

More or less the same issue as the previous comment. I don't see a benefit in forbidding uppercase letters at all.

[c-vetter]

connected with #16

[hildjj]

Another edge case that I hit all the time: e.g. and i.e.:

  /**
   * Any kind of fowl (e.g. a duck).
   */

There's a whole list of these here: https://en.wikipedia.org/wiki/List_of_Latin_abbreviations

[brettz9]

@cscott : I am not aware of --- being acceptable as a form of punctuation. What are you using it for?

I marked the mistaken-caps-after-colon issue as resolved, as it appears no longer to be an issue.

@jugglinmike : We couldn't possibly detect all of the proper nouns, so you'd need to work around it.

@c-vetter : I do not see any error at this point for the code you provided, so it has apparently since been resolved.

@hildjj : As per usage on the site you linked, e.g. and i.e. are to be followed by a comma. In such cases, our code works as expected.

[cscott]

@brettz9 It's been five years --- I can't recall the exact text which prompted filing the bug at this point. But the preceding is an example of the use of a long dash. Some folks type it with two or three ascii hyphens; see https://en.wikipedia.org/wiki/Dash#Approximating_the_em_dash_with_two_or_three_hyphens and similarly spacing around the dash seems to vary between British and American usage: https://en.wikipedia.org/wiki/Dash#Typographic_details

I suspect there are also uses of consecutive hyphens as a horizontal line, such as:

/**
 * This is a function to ....
 * ----------------------------
 * NOTE: older versions of this function....
 */

In our codebase (MediaWiki) there are also uses of the two-dash version, like:

		 * If the format is 'jpg', will also add a random orientation -- the
		 * image will be drawn rotated with triangle points facing in some
		 * direction (0, 90, 180 or 270 degrees) and a countering rotation
		 * should turn the triangle points upward again.
		 */

Hopefully that will help you write a regression test, whether or not the original bug has been fixed sometime in the past 5 years.

[github-actions[bot]]

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

The release is available on:

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

Your semantic-release bot :package::rocket:

[brettz9]

Thanks. I've protected backtick content and allowed it as the end of a "sentence", but I think dashes—even line separator ones—ought not prevent the rule from reporting missing terminal punctuation since I think it is in the spirit of the rule to add grammatical strictness.