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

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions