Update doc comments guidelines (#3037) (#3412)

(cherry picked from commit ddf9cd9)

Co-authored-by: Florian Bernd <[email protected]>

Author: pquentin

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