.README/README.md

@@ -461,6 +461,42 @@ your files' code which are of interest to check. However, in
 `eslint-plugin-jsdoc`, we also allow you to use these selectors to define
 additional contexts where you wish our own rules to be applied.
 
+#### `contexts` format
+
+While at their simplest, these can be an array of string selectors, one can
+also supply an object with `context` (in place of the string) and one of two
+properties:
+
+1. For `require-jsdoc`, there is also a `inlineCommentBlock` property. See
+    that rule for details.
+1. For `no-missing-syntax` and `no-restricted-syntax`, there is also a
+    `message` property which allows customization of the message to be shown
+    when the rule is triggered.
+1. For `no-missing-syntax`, there is also a `minimum` property. See that rule.
+1. For other rules, there is a `comment` property which adds to the `context`
+    in requiring that the `comment` AST condition is also met, e.g., to
+    require that certain tags are present and/or or types and type operators
+    are in use. Note that this AST (either for `JSDoc*` or `JSDocType*` AST)
+    has not been standardized and should be considered experimental.
+    Note that this property might also become obsolete if parsers begin to
+    include JSDoc-structured AST. A
+    [parser](https://github.com/brettz9/jsdoc-eslint-parser/) is available
+    which aims to support comment AST as
+    a first class citizen where comment/comment types can be used anywhere
+    within a normal AST selector but this should only be considered
+    experimental. When using such a parser, you need not use `comment` and
+    can just use a plain string context. The determination of the node on
+    which the comment is attached is also subject to change. It may be
+    currently possible for different structures to map to the same comment
+    block. This is because normally when querying to find either the
+    declaration of the function expression for
+    `const quux = function () {}`, the associated comment would,
+    in both cases, generally be expected to be on the line above both, rather
+    than to be immediately preceding the funciton (in the case of the
+    function).
+
+#### Discovering available AST definitions
+
 To know all of the AST definitions one may target, it will depend on the
 [parser](https://eslint.org/docs/user-guide/configuring#specifying-parser)
 you are using with ESLint (e.g., `espree` is the default parser for ESLint,
@@ -473,11 +509,13 @@ So you can look up a particular parser to see its rules, e.g., browse through
 the [ESTree docs](https://github.com/estree/estree) as used by Espree or see
 ESLint's [overview of the structure of AST](https://eslint.org/docs/developer-guide/working-with-custom-parsers#the-ast-specification).
 
-However, it can sometimes be even more helpful to get an idea of ASt by just
+However, it can sometimes be even more helpful to get an idea of AST by just
 providing some of your JavaScript to the wonderful
 [AST Explorer](https://astexplorer.net/) tool and see what AST is built out
 of your code. You can set the tool to the specific parser which you are using.
 
+#### Uses/Tips for AST
+
 And if you wish to introspect on the AST of code within your projects, you can
 use [eslint-plugin-query](https://github.com/brettz9/eslint-plugin-query).
 Though it also works as a plugin, you can use it with its own CLI, e.g.,
@@ -515,6 +553,8 @@ selector).
 {"gitdown": "include", "file": "./rules/newline-after-description.md"}
 {"gitdown": "include", "file": "./rules/no-bad-blocks.md"}
 {"gitdown": "include", "file": "./rules/no-defaults.md"}
+{"gitdown": "include", "file": "./rules/no-missing-syntax.md"}
+{"gitdown": "include", "file": "./rules/no-restricted-syntax.md"}
 {"gitdown": "include", "file": "./rules/no-types.md"}
 {"gitdown": "include", "file": "./rules/no-undefined-types.md"}
 {"gitdown": "include", "file": "./rules/require-description-complete-sentence.md"}

.README/rules/implements-on-classes.md

@@ -13,8 +13,8 @@ function is adhering.
 
 ##### `contexts`
 
-Set this to an array of strings representing the AST context
-where you wish the rule to be applied.
+Set this to an array of strings representing the AST context (or an object with
+`context` and `comment` properties) where you wish the rule to be applied.
 
 Overrides the default contexts (see below). Set to `"any"` if you want
 the rule to apply to any jsdoc block throughout your files (as is necessary

.README/rules/match-description.md

@@ -96,8 +96,9 @@ checking it by setting it to `false`.
 
 ##### `contexts`
 
-Set this to an array of strings representing the AST context
-where you wish the rule to be applied (e.g., `ClassDeclaration` for ES6
+Set this to an array of strings representing the AST context (or an object with
+`context` and `comment` properties) where you wish the rule to be applied.
+(e.g., `ClassDeclaration` for ES6
 classes). Overrides the default contexts (see below). Set to `"any"` if you
 want the rule to apply to any jsdoc block throughout your files.
 

.README/rules/no-defaults.md

@@ -24,8 +24,8 @@ the presence of ES6 default parameters (bearing in mind that such
 
 ##### `contexts`
 
-Set this to an array of strings representing the AST context
-where you wish the rule to be applied.
+Set this to an array of strings representing the AST context (or an object with
+`context` and `comment` properties) where you wish the rule to be applied.
 Overrides the default contexts (see below). Set to `"any"` if you want
 the rule to apply to any jsdoc block throughout your files (as is necessary
 for finding function blocks not attached to a function declaration or

.README/rules/no-missing-syntax.md

@@ -0,0 +1,62 @@
+### `no-missing-syntax`
+
+This rule lets you report when certain comment structures are always expected.
+This rule might be especially useful with [`overrides`](https://eslint.org/docs/user-guide/configuring/configuration-files#how-do-overrides-work)
+where you need only require tags and/or types within specific directories
+(e.g., to enforce that a plugins or locale directory always has a certain form
+of export).
+
+This (along with `no-restricted-syntax`) is a bit similar to Schematron for
+XML or jsontron for JSON--you can validate expectations of there being
+arbitrary structures.
+
+This differs from the rule of the same name in [`eslint-plugin-query`](https://github.com/brettz9/eslint-plugin-query)
+in that this always looks for a comment above a structure (whether or not
+you have a `comment` condition).
+
+In addition to being generally useful for precision in requiring contexts,
+it is hoped that the ability to specify required tags on structures can
+be used for requiring `@type` or other types for a minimalist yet adequate
+specification of types which can be used to compile JavaScript+JSDoc (JJ)
+to WebAssembly (e.g., by converting it to TypeSscript and then using
+AssemblyScript to convert to WebAssembly). (It may be possible that one
+will need to require types with certain structures beyond function
+declarations and the like, as well as optionally requiring specification
+of number types.)
+
+Note that you can use selectors which make use of negators like `:not()`
+including with asterisk, e.g., `*:not(FunctionDeclaration)` to indicate types
+which are not adequate to satisfy a condition, e.g.,
+`FunctionDeclaration:not(FunctionDeclaration[id.name="ignoreMe"])` would
+not report if there were only a function declaration of the name "ignoreMe"
+(though it would report by function declarations of other names).
+
+#### Options
+
+##### `contexts`
+
+Set this to an array of strings representing the AST context (or an object with
+`context` and `comment` properties) where you wish the rule to be applied.
+
+Use the `minimum` property (defaults to 1) to indicate how many are required
+for the rule to be reported.
+
+Use the `message` property to indicate the specific error to be shown when an
+error is reported for that context being found missing.
+
+Set to `"any"` if you want the rule to apply to any jsdoc block throughout
+your files (as is necessary for finding function blocks not attached to a
+function declaration or expression, i.e., `@callback` or `@function` (or its
+aliases `@func` or `@method`) (including those associated with an `@interface`).
+
+See the ["AST and Selectors"](#eslint-plugin-jsdoc-advanced-ast-and-selectors)
+section of our README for more on the expected format.
+
+|||
+|---|---|
+|Context|None except those indicated by `contexts`|
+|Tags|Any if indicated by AST|
+|Recommended|false|
+|Options|`contexts`|
+
+<!-- assertions noMissingSyntax -->

.README/rules/no-restricted-syntax.md

@@ -0,0 +1,42 @@
+### `no-restricted-syntax`
+
+Reports when certain comment structures are present.
+
+Note that this rule differs from ESLint's [no-restricted-syntax](https://eslint.org/docs/rules/no-restricted-syntax)
+rule in expecting values within a single options object's
+`contexts` property, and with the property `context` being used in place of
+`selector` (as well as allowing for `comment`). The format also differs from
+the format expected by [`eslint-plugin-query`](https://github.com/brettz9/eslint-plugin-query).
+
+Unlike those rules, this is specific to finding comments attached to
+structures, (whether or not you add a specific `comment` condition).
+
+Note that if your parser supports comment AST (as [jsdoc-eslint-parser/](https://github.com/brettz9/jsdoc-eslint-parser/) is designed to do), you can just use ESLint's
+rule.
+
+#### Options
+
+##### `contexts`
+
+Set this to an array of strings representing the AST context (or an object with
+`context` and `comment` properties) where you wish the rule to be applied.
+
+Use the `message` property to indicate the specific error to be shown when an
+error is reported for that context being found.
+
+Set to `"any"` if you want the rule to apply to any jsdoc block throughout
+your files (as is necessary for finding function blocks not attached to a
+function declaration or expression, i.e., `@callback` or `@function` (or its
+aliases `@func` or `@method`) (including those associated with an `@interface`).
+
+See the ["AST and Selectors"](#eslint-plugin-jsdoc-advanced-ast-and-selectors)
+section of our README for more on the expected format.
+
+|||
+|---|---|
+|Context|None except those indicated by `contexts`|
+|Tags|Any if indicated by AST|
+|Recommended|false|
+|Options|`contexts`|
+
+<!-- assertions noRestrictedSyntax -->

.README/rules/no-types.md

@@ -9,8 +9,8 @@ the type information would be redundant with TypeScript.
 
 ##### `contexts`
 
-Set this to an array of strings representing the AST context
-where you wish the rule to be applied.
+Set this to an array of strings representing the AST context (or an object with
+`context` and `comment` properties) where you wish the rule to be applied.
 Overrides the default contexts (see below). Set to `"any"` if you want
 the rule to apply to any jsdoc block throughout your files (as is necessary
 for finding function blocks not attached to a function declaration or

.README/rules/require-example.md

@@ -25,8 +25,9 @@ missing `@example` declarations.
 
 ##### `contexts`
 
-Set this to an array of strings representing the AST context
-where you wish the rule to be applied (e.g., `ClassDeclaration` for ES6
+Set this to an array of strings representing the AST context (or an object with
+`context` and `comment` properties) where you wish the rule to be applied.
+(e.g., `ClassDeclaration` for ES6
 classes). Overrides the default contexts (see below). Set to `"any"` if you
 want the rule to apply to any jsdoc block throughout your files.
 

.README/rules/require-param-description.md

@@ -6,8 +6,8 @@ Requires that each `@param` tag has a `description` value.
 
 ##### `contexts`
 
-Set this to an array of strings representing the AST context
-where you wish the rule to be applied.
+Set this to an array of strings representing the AST context (or an object with
+`context` and `comment` properties) where you wish the rule to be applied.
 Overrides the default contexts (see below). Set to `"any"` if you want
 the rule to apply to any jsdoc block throughout your files (as is necessary
 for finding function blocks not attached to a function declaration or

.README/rules/require-param-name.md

@@ -10,8 +10,8 @@ Requires that all function parameters have names.
 
 ##### `contexts`
 
-Set this to an array of strings representing the AST context
-where you wish the rule to be applied.
+Set this to an array of strings representing the AST context (or an object with
+`context` and `comment` properties) where you wish the rule to be applied.
 Overrides the default contexts (see below). Set to `"any"` if you want
 the rule to apply to any jsdoc block throughout your files (as is necessary
 for finding function blocks not attached to a function declaration or

.README/rules/require-param-type.md

@@ -6,8 +6,8 @@ Requires that each `@param` tag has a `type` value.
 
 ##### `contexts`
 
-Set this to an array of strings representing the AST context
-where you wish the rule to be applied.
+Set this to an array of strings representing the AST context (or an object with
+`context` and `comment` properties) where you wish the rule to be applied.
 Overrides the default contexts (see below). Set to `"any"` if you want
 the rule to apply to any jsdoc block throughout your files (as is necessary
 for finding function blocks not attached to a function declaration or

.README/rules/require-param.md

@@ -324,9 +324,9 @@ need destructuring.
 
 ##### `contexts`
 
-Set this to an array of strings representing the AST context
-where you wish the rule to be applied. Overrides the default
-contexts (see below). May be useful for adding such as
+Set this to an array of strings representing the AST context (or an object with
+`context` and `comment` properties) where you wish the rule to be applied.
+Overrides the default contexts (see below). May be useful for adding such as
 `TSMethodSignature` in TypeScript or restricting the contexts
 which are checked.
 

.README/rules/require-returns-description.md

@@ -8,8 +8,8 @@ or if it is `Promise<void>` or `Promise<undefined>`.
 
 ##### `contexts`
 
-Set this to an array of strings representing the AST context
-where you wish the rule to be applied.
+Set this to an array of strings representing the AST context (or an object with
+`context` and `comment` properties) where you wish the rule to be applied.
 Overrides the default contexts (see below). Set to `"any"` if you want
 the rule to apply to any jsdoc block throughout your files (as is necessary
 for finding function blocks not attached to a function declaration or

.README/rules/require-returns-type.md

@@ -6,8 +6,8 @@ Requires that `@returns` tag has `type` value.
 
 ##### `contexts`
 
-Set this to an array of strings representing the AST context
-where you wish the rule to be applied.
+Set this to an array of strings representing the AST context (or an object with
+`context` and `comment` properties) where you wish the rule to be applied.
 Overrides the default contexts (see below). Set to `"any"` if you want
 the rule to apply to any jsdoc block throughout your files (as is necessary
 for finding function blocks not attached to a function declaration or

.README/rules/require-returns.md

@@ -28,7 +28,8 @@ Will also report if multiple `@returns` tags are present.
     object. This may be useful for flagging that there has been consideration
     of return type. Defaults to `false`.
 - `contexts` - Set this to an array of strings representing the AST context
-    where you wish the rule to be applied.
+    (or an object with `context` and `comment` properties) where you wish
+    the rule to be applied.
     Overrides the default contexts (see below). Set to `"any"` if you want
     the rule to apply to any jsdoc block throughout your files (as is necessary
     for finding function blocks not attached to a function declaration or

.README/rules/require-throws.md

@@ -10,7 +10,8 @@ Requires that throw statements are documented.
     so be sure to add back `inheritdoc` if you wish its presence to cause
     exemption of the rule.
 - `contexts` - Set this to an array of strings representing the AST context
-    where you wish the rule to be applied.
+    (or an object with `context` and `comment` properties) where you wish
+    the rule to be applied.
     Overrides the default contexts (see below). Set to `"any"` if you want
     the rule to apply to any jsdoc block throughout your files (as is necessary
     for finding function blocks not attached to a function declaration or

.README/rules/require-yields.md

@@ -20,7 +20,8 @@ option to expect a non-standard `@next` tag.
     that a project is aware of an `undefined`/`void` yield. Defaults to
     `false`.
 - `contexts` - Set this to an array of strings representing the AST context
-    where you wish the rule to be applied.
+    (or an object with `context` and `comment` properties) where you wish
+    the rule to be applied.
     Overrides the default contexts (see below). Set to `"any"` if you want
     the rule to apply to any jsdoc block throughout your files (as is necessary
     for finding function blocks not attached to a function declaration or