Skip to content

Enforce JSDoc block comments #5786

@pquentin

Description

@pquentin

Right now, the compiler only looks at JSDoc comments for descriptions and annotations. JSDoc ignores comments that don't start with /**, including /*** with three stars.

For example, all those comments are ignored, and the compiler currently uses rest-api-spec to fill them in:

path_parts: {
/*
* A list of indices, data streams, or aliases to search.
* It supports wildcards (`*`).
* To search all data streams and indices, omit this parameter or use `*` or `_all`.
* To search a remote cluster, use the `<cluster>:<target>` syntax.
*/
index: Indices
/*
* A field that contains the geospatial data to return.
* It must be a `geo_point` or `geo_shape` field.
* The field must have doc values enabled. It cannot be a nested field.
*
* NOTE: Vector tiles do not natively support geometry collections.
* For `geometrycollection` values in a `geo_shape` field, the API returns a hits layer feature for each element of the collection.
* This behavior may change in a future release.
*/
field: Field
/* The zoom level of the vector tile to search. It accepts `0` to `29`. */
zoom: ZoomLevel
/* The X coordinate for the vector tile to search. */
x: Coordinate
/* The Y coordinate for the vector tile to search. */
y: Coordinate
}

To fix this, I suggest we only accept two types of comments:

  1. JSDoc-style comments starting with /**, and
  2. // line comments when we don't want a given comment to be interpreted by the compiler.

Metadata

Metadata

Assignees

Type

No type
No fields configured for issues without a type.

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions