From 08baa793139700aef05a0916353d9e583f63e9bc Mon Sep 17 00:00:00 2001 From: Florian Bernd Date: Tue, 22 Oct 2024 08:58:18 +0200 Subject: [PATCH] Update doc comments guidelines --- docs/doc-comments-guide.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/doc-comments-guide.md b/docs/doc-comments-guide.md index d801c7a8dd..a8775a49fc 100644 --- a/docs/doc-comments-guide.md +++ b/docs/doc-comments-guide.md @@ -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