Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[8.x] Update doc comments guidelines (#3037) #3412

Merged
merged 1 commit into from
Jan 2, 2025
Merged

[8.x] Update doc comments guidelines (#3037) #3412

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 6 additions & 2 deletions docs/doc-comments-guide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,16 +7,20 @@ Documentation of the TypeScript specification is made using [JSDoc](https://jsdo
The first phrase is used as the mandatory operation summary in the OpenAPI document.
Refer to [API documentation guidelines](https://docs.elastic.dev/content-architecture/oas#summaries).

NOTE: You must add a period or `\n` at the end of the phrase for it to parse correctly.
The period will be properly omitted from the output OpenAPI document.
> [!NOTE]
> You must add a period at the end of the phrase for it to parse correctly. The period will be properly omitted from the output OpenAPI document.

Additional lines start with a `*` followed by a space. Long lines are allowed but it's better if text is formatted to a maximum of 120 characters per line.

> [!NOTE]
> A blank line must be inserted between the first sentence and all subsequent lines to ensure correct formatting in all places (e.g. in the in-code documentation of the language clients).

## Example

```ts
/**
* Get ranking evaluation.
*
* Enables you to evaluate the quality of ranked search results over a set of typical search queries.
* @rest_spec_name rank_eval
* @availability stack since=6.2.0 stability=stable
Expand Down
Loading