# require-description-complete-sentence
* [Fixer](#user-content-require-description-complete-sentence-fixer)
* [Options](#user-content-require-description-complete-sentence-options)
* [`abbreviations`](#user-content-require-description-complete-sentence-options-abbreviations)
* [`newlineBeforeCapsAssumesBadSentenceEnd`](#user-content-require-description-complete-sentence-options-newlinebeforecapsassumesbadsentenceend)
* [`tags`](#user-content-require-description-complete-sentence-options-tags)
* [Context and settings](#user-content-require-description-complete-sentence-context-and-settings)
* [Failing examples](#user-content-require-description-complete-sentence-failing-examples)
* [Passing examples](#user-content-require-description-complete-sentence-passing-examples)
Requires that block description, explicit `@description`, and
`@param`/`@returns` tag descriptions are written in complete sentences, i.e.,
* Description must start with an uppercase alphabetical character.
* Paragraphs must start with an uppercase alphabetical character.
* Sentences must end with a period, question mark, exclamation mark, or triple backticks.
* Every line in a paragraph (except the first) which starts with an uppercase
character must be preceded by a line ending with a period.
* A colon or semi-colon followed by two line breaks is still part of the
containing paragraph (unlike normal dual line breaks).
* Text within inline tags `{...}` or within triple backticks are not checked for sentence divisions.
* Periods after items within the `abbreviations` option array are not treated
as sentence endings.
## Fixer
If sentences do not end with terminal punctuation, a period will be added.
If sentences do not start with an uppercase character, the initial
letter will be capitalized.
## Options
A single options object has the following properties.
### abbreviations
You can provide an `abbreviations` options array to avoid such strings of text
being treated as sentence endings when followed by dots. The `.` is not
necessary at the end of the array items.
### newlineBeforeCapsAssumesBadSentenceEnd
When `false` (the new default), we will not assume capital letters after
newlines are an incorrect way to end the sentence (they may be proper
nouns, for example).
### tags
If you want additional tags to be checked for their descriptions, you may
add them within this option.
```js
{
'jsdoc/require-description-complete-sentence': ['error', {
tags: ['see', 'copyright']
}]
}
```
The tags `@param`/`@arg`/`@argument` and `@property`/`@prop` will be properly
parsed to ensure that the checked "description" text includes only the text
after the name.
All other tags will treat the text following the tag name, a space, and
an optional curly-bracketed type expression (and another space) as part of
its "description" (e.g., for `@returns {someType} some description`, the
description is `some description` while for `@some-tag xyz`, the description
is `xyz`).
## Context and settings
|||
|---|---|
|Context|everywhere|
|Tags|doc block, `param`, `returns`, `description`, `property`, `summary`, `file`, `classdesc`, `todo`, `deprecated`, `throws`, 'yields' and others added by `tags`|
|Aliases|`arg`, `argument`, `return`, `desc`, `prop`, `fileoverview`, `overview`, `exception`, `yield`|
|Recommended|false|
|Options|`abbreviations`, `newlineBeforeCapsAssumesBadSentenceEnd`, `tags`|
## Failing examples
The following patterns are considered problems:
````ts
/**
* foo.
*/
function quux () {
}
// Message: Sentences should start with an uppercase character.
/**
* foo?
*/
function quux () {
}
// Message: Sentences should start with an uppercase character.
/**
* @description foo.
*/
function quux () {
}
// Message: Sentences should start with an uppercase character.
/**
* Foo)
*/
function quux () {
}
// Message: Sentences must end with a period.
/**
* `foo` is a variable
*/
function quux () {
}
// Message: Sentences must end with a period.
/**
* Foo.
*
* foo.
*/
function quux () {
}
// Message: Sentences should start with an uppercase character.
/**
* тест.
*/
function quux () {
}
// Message: Sentences should start with an uppercase character.
/**
* Foo
*/
function quux () {
}
// Message: Sentences must end with a period.
/**
* Foo
*
* @param x
*/
function quux () {
}
// Message: Sentences must end with a period.
/**
* Foo
* Bar.
*/
function quux () {
}
// "jsdoc/require-description-complete-sentence": ["error"|"warn", {"newlineBeforeCapsAssumesBadSentenceEnd":true}]
// Message: A line of text is started with an uppercase character, but the preceding line does not end the sentence.
/**
* Foo.
*
* @param foo foo.
*/
function quux (foo) {
}
// Message: Sentences should start with an uppercase character.
/**
* Foo.
*
* @param foo bar
*/
function quux (foo) {
}
// Message: Sentences should start with an uppercase character.
/**
* {@see Foo.bar} buz
*/
function quux (foo) {
}
// Message: Sentences must end with a period.
/**
* Foo.
*
* @returns {number} foo
*/
function quux (foo) {
}
// Message: Sentences should start with an uppercase character.
/**
* Foo.
*
* @returns foo.
*/
function quux (foo) {
}
// Message: Sentences should start with an uppercase character.
/**
* lorem ipsum dolor sit amet, consectetur adipiscing elit. pellentesque elit diam,
* iaculis eu dignissim sed, ultrices sed nisi. nulla at ligula auctor, consectetur neque sed,
* tincidunt nibh. vivamus sit amet vulputate ligula. vivamus interdum elementum nisl,
* vitae rutrum tortor semper ut. morbi porta ante vitae dictum fermentum.
* proin ut nulla at quam convallis gravida in id elit. sed dolor mauris, blandit quis ante at,
* consequat auctor magna. duis pharetra purus in porttitor mollis.
*/
function longDescription (foo) {
}
// Message: Sentences should start with an uppercase character.
/**
* @arg {number} foo - Foo
*/
function quux (foo) {
}
// Message: Sentences must end with a period.
/**
* @argument {number} foo - Foo
*/
function quux (foo) {
}
// Message: Sentences must end with a period.
/**
* @return {number} foo
*/
function quux (foo) {
}
// Message: Sentences should start with an uppercase character.
/**
* Returns bar.
*
* @return {number} bar
*/
function quux (foo) {
}
// Message: Sentences should start with an uppercase character.
/**
* @throws {object} Hello World
* hello world
*/
// Message: Sentences must end with a period.
/**
* @summary Foo
*/
function quux () {
}
// Message: Sentences must end with a period.
/**
* @throws {SomeType} Foo
*/
function quux () {
}
// Message: Sentences must end with a period.
/**
* @see Foo
*/
function quux () {
}
// "jsdoc/require-description-complete-sentence": ["error"|"warn", {"tags":["see"]}]
// Message: Sentences must end with a period.
/**
* @param foo Foo bar
*/
function quux (foo) {
}
// Settings: {"jsdoc":{"tagNamePreference":{"description":false}}}
// "jsdoc/require-description-complete-sentence": ["error"|"warn", {"tags":["param"]}]
// Message: Sentences must end with a period.
/**
* Sorry, but this isn't a complete sentence, Mr.
*/
function quux () {
}
// "jsdoc/require-description-complete-sentence": ["error"|"warn", {"abbreviations":["Mr"]}]
// Message: Sentences must end with a period.
/**
* Sorry, but this isn't a complete sentence Mr.
*/
function quux () {
}
// "jsdoc/require-description-complete-sentence": ["error"|"warn", {"abbreviations":["Mr."]}]
// Message: Sentences must end with a period.
/**
* Sorry, but this isn't a complete sentence Mr.
*/
function quux () {
}
// "jsdoc/require-description-complete-sentence": ["error"|"warn", {"abbreviations":["Mr"]}]
// Message: Sentences must end with a period.
/**
* Sorry, but this isn't a complete sentence Mr. and Mrs.
*/
function quux () {
}
// "jsdoc/require-description-complete-sentence": ["error"|"warn", {"abbreviations":["Mr","Mrs"]}]
// Message: Sentences must end with a period.
/**
* This is a complete sentence. But this isn't, Mr.
*/
function quux () {
}
// "jsdoc/require-description-complete-sentence": ["error"|"warn", {"abbreviations":["Mr"]}]
// Message: Sentences must end with a period.
/**
* This is a complete Mr. sentence. But this isn't, Mr.
*/
function quux () {
}
// "jsdoc/require-description-complete-sentence": ["error"|"warn", {"abbreviations":["Mr"]}]
// Message: Sentences must end with a period.
/**
* This is a complete Mr. sentence.
*/
function quux () {
}
// Message: Sentences should start with an uppercase character.
/**
* This is fun, i.e. enjoyable, but not superlatively so, e.g. not
* super, wonderful, etc..
*/
function quux () {
}
// Message: Sentences should start with an uppercase character.
/**
* Do not have dynamic content; e.g. homepage. Here a simple unique id
* suffices.
*/
function quux () {
}
// Message: Sentences should start with an uppercase character.
/**
* Implements support for the
* Swahili voice synthesizer.
*/
function speak() {
}
// "jsdoc/require-description-complete-sentence": ["error"|"warn", {"newlineBeforeCapsAssumesBadSentenceEnd":true}]
// Message: A line of text is started with an uppercase character, but the preceding line does not end the sentence.
/**
* Foo.
*
* @template TempA, TempB foo.
*/
function quux (foo) {
}
// "jsdoc/require-description-complete-sentence": ["error"|"warn", {"tags":["template"]}]
// Message: Sentences should start with an uppercase character.
/**
* Just a component.
* @param {Object} props Свойства.
* @return {ReactElement}.
*/
function quux () {}
// Message: Sentences must be more than punctuation.
````
## Passing examples
The following patterns are not considered problems:
````ts
/**
* @param foo - Foo.
*/
function quux () {
}
/**
* Foo.
*/
function quux () {
}
/**
* Foo.
* Bar.
*/
function quux () {
}
/**
* Foo.
*
* Bar.
*/
function quux () {
}
/**
* Тест.
*/
function quux () {
}
/**
* Foo
* bar.
*/
function quux () {
}
/**
* @returns Foo bar.
*/
function quux () {
}
/**
* Foo {@see Math.sin}.
*/
function quux () {
}
/**
* Foo {@see Math.sin} bar.
*/
function quux () {
}
/**
* Foo?
*
* Bar!
*
* Baz:
* 1. Foo.
* 2. Bar.
*/
function quux () {
}
/**
* Hello:
* World.
*/
function quux () {
}
/**
* Hello: world.
*/
function quux () {
}
/**
*
*/
function quux () {
}
/**
* @description Foo.
*/
function quux () {
}
/**
* `foo` is a variable.
*/
function quux () {
}
/**
* Foo.
*
* `foo`.
*/
function quux () {
}
/**
* @param foo - `bar`.
*/
function quux () {
}
/**
* @returns {number} `foo`.
*/
function quux () {
}
/**
* Foo
* `bar`.
*/
function quux () {
}
/**
* @example Foo
*/
function quux () {
}
/**
* @see Foo
*/
function quux () {
}
/**
* Foo.
*
* @param foo Foo.
*/
function quux (foo) {
}
/**
* Foo.
*
* @param foo Foo.
*/
function quux (foo) {
}
// "jsdoc/require-description-complete-sentence": ["error"|"warn", {"tags":["param"]}]
/**
* @param foo Foo bar.
*/
function quux (foo) {
}
// Settings: {"jsdoc":{"tagNamePreference":{"description":false}}}
// "jsdoc/require-description-complete-sentence": ["error"|"warn", {"tags":["param"]}]
/**
*
*/
function quux (foo) {
}
// Settings: {"jsdoc":{"tagNamePreference":{"description":false}}}
/**
* We stop loading Items when we have loaded:
*
* 1) The main Item;
* 2) All its variants.
*/
/**
* This method is working on 2 steps.
*
* | Step | Comment |
* |------|-------------|
* | 1 | do it |
* | 2 | do it again |
*/
/**
* This is something that
* I want to test.
*/
function quux () {
}
/**
* When making HTTP requests, the
* URL is super important.
*/
function quux () {
}
/**
* Sorry, but this isn't a complete sentence, Mr.
*/
function quux () {
}
/**
* Sorry, but this isn't a complete sentence Mr..
*/
function quux () {
}
// "jsdoc/require-description-complete-sentence": ["error"|"warn", {"abbreviations":["Mr."]}]
/**
* Sorry, but this isn't a complete sentence Mr.
*/
function quux () {
}
/**
* Sorry, but this isn't a complete sentence Mr. and Mrs..
*/
function quux () {
}
// "jsdoc/require-description-complete-sentence": ["error"|"warn", {"abbreviations":["Mr","Mrs"]}]
/**
* This is a complete sentence aMr.
*/
function quux () {
}
// "jsdoc/require-description-complete-sentence": ["error"|"warn", {"abbreviations":["Mr"]}]
/**
* This is a complete sentence. But this isn't, Mr.
*/
function quux () {
}
/**
* This is a complete Mr. Sentence. But this isn't, Mr.
*/
function quux () {
}
/**
* This is a complete Mr. sentence.
*/
function quux () {
}
// "jsdoc/require-description-complete-sentence": ["error"|"warn", {"abbreviations":["Mr"]}]
/**
* This is fun, i.e. enjoyable, but not superlatively so, e.g. not
* super, wonderful, etc..
*/
function quux () {
}
// "jsdoc/require-description-complete-sentence": ["error"|"warn", {"abbreviations":["etc","e.g.","i.e."]}]
**
* Do not have dynamic content; e.g. homepage. Here a simple unique id
* suffices.
*/
function quux () {
}
// "jsdoc/require-description-complete-sentence": ["error"|"warn", {"abbreviations":["etc","e.g.","i.e."]}]
/**
* Implements support for the
* Swahili voice synthesizer.
*/
function speak() {
}
/**
* @param foo
*
* @returns {void}
*/
export default (foo) => {
foo()
}
/** @file To learn more,
* see: https://github.com/d3/d3-ease. */
/** To learn more,
* see: https://github.com/d3/d3-ease. */
/**
* This is a complete sentence...
*/
function quux () {
}
/**
* He wanted a few items: a jacket and shirt...
*/
function quux () {
}
/**
* The code in question was...
* ```
* alert('hello');
* ```
*/
function quux () {
}
/**
* @param {number|string|Date|Object|OverType|WhateverElse} multiType -
* Nice long explanation...
*/
function test (multiType) {
}
/**
* Any kind of fowl (e.g., a duck).
*/
function quux () {}
/**
* The code in question was...
* ```
* do something
*
* interesting
* ```
*/
function quux () {
}
/** @param options {@link RequestOptions} specifying path parameters and query parameters. */
/**
* A single line for testing.
*
* ```js
* const aCodeExample = true;
* ```
*
* @param parameter
*/
const code = (parameter) => 123;
/**
* ### Overview
* My class is doing.
*
* ### Example
* ```javascript
* const toto = 'toto';
* ```
*/
export class ClassExemple {
}
/** {@inheritDoc SomeClass} */
````