Add documentation on spec documentation (#638)

Author: swallez

docs/doc-comments-guide.md

@@ -0,0 +1,90 @@
+# Documenting the API specification
+
+A specification is not only about formalizing data structures, it's also about explaining what these structures and their properties are used for.
+
+Documentation of the TypeScript specification is made using [JSDoc](https://jsdoc.app/) comments, i.e. multiline comments starting with `/**` above a type or field declaration.
+
+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.
+
+## Example
+
+```ts
+/**
+ * @rest_spec_name rank_eval
+ * @since 6.2.0
+ */
+export interface Request extends RequestBase {
+  path_parts: {
+    /**
+     * List of data streams, indices, and index aliases used to limit the request. Wildcard (`*`) expressions are supported.
+     * 
+     * To target all data streams and indices in a cluster, omit this parameter or use `_all` or `*`.
+     */
+    index: Indices
+  }
+  query_parameters?: {
+    /**
+     * Accept no matching indices?
+     * 
+     * If `false`, the request returns an error if any wildcard expression, index alias, or _all value targets only
+     * missing or closed indices. This behavior applies even if the request targets other open indices. For example,
+     * a request targeting `foo*,bar*` returns an error if an index starts with `foo` but no index starts with `bar`.
+     * 
+     * @server_default true
+     */
+    allow_no_indices?: boolean
+    
+    expand_wildcards?: ExpandWildcards
+    
+    /**
+     * If `true`, missing or closed indices are not included in the response.
+     * @server_default false
+     */
+    ignore_unavailable?: boolean
+    
+    search_type?: string
+  }
+  body: {
+    /**
+     * A set of typical search requests, together with their provided ratings.
+     */
+    requests: RankEvalRequestItem[]
+    
+    /**
+     * Definition of the evaluation metric to calculate.
+     * 
+     * @doc_url https://www.elastic.co/guide/en/elasticsearch/reference/current/search-rank-eval.html#_available_evaluation_metrics
+     */
+    metric?: RankEvalMetric
+  }
+}
+```
+
+([original source code](https://github.com/elastic/elasticsearch-specification/blob/main/specification/_global/rank_eval/RankEvalRequest.ts))
+
+
+## Markup language
+
+The specification is the starting point for a number of generators that produce a large range of artifacts, starting with source code in 10 different programming languages. It's essential for the API documentation to be part of these generated artifacts, e.g. to provide autocompletion help in IDEs when using a client library.
+
+Each of these targets has a different way to format inline documentation: Java code uses HTML, Python uses reStructuredText, Rust uses Markdown, etc. To enable rich documentation to be output, the specification doc comments must not be just plain text, but use a well-defined markup language so that generators can reliably transcode them to their target representation.
+
+**We have settled on using [GitHub Flavored Markdown](https://github.github.com/gfm/) (GFM) for doc comments.** It is based on the well-defined [CommonMark](https://commonmark.org/) specification with a few additions, most notably tables.
+
+GFM also has implementations in most languages, meaning that code generators will be able to easily parse the doc comments and transcode them.
+
+## Structuring a doc-comment
+
+### Terseness
+
+**Doc comments are reference material**: they should be as succinct as possible while capturing all the necessary information to use the elements they're documenting. Remember that they will often show up in small IDE autocompletion popups!
+
+In particular, doc comments are not the right place for tutorials or examples, which should be in dedicated documentation pages. These pages can of course be linked from the doc comments.
+
+API endpoints will also have a `@doc_url` JSDoc tag that links to that API's detailed documentation page.
+
+### Multi-paragraph doc comments
+
+A single sentence is not always enough to explain a type or a field and doc comments will have multiple paragraphs. It is important that **the first paragraph provides a self-contained description** of the item that is being documented. The reason is twofold:
+- people skim documentation quickly and should get the gist of the information from that first sentence, and read others if they want to dive in,
+- Some IDEs may choose to display only the first paragraph or even the first sentence of a doc-comment in their help popup to keep it small, and then require an additional action from the user to display the full text.

docs/modeling-guide.md

@@ -9,6 +9,8 @@ the basic types [here](https://www.typescriptlang.org/docs/handbook/basic-types.
 while in [behaviors](./behaviors.md) you can find the list of special interfaces used
 for describing APIs that can't be represented in the specification.
 
+Refer to the [documentation guide](doc-comments-guide.md) to add documentation to types and fields.
+
 ### Dictionary
 
 Represents a dynamic key value map:
@@ -393,7 +395,7 @@ class FooRequest {
 
 #### description
 
-You can add a description for each property, in this case there is no need to use a JSDoc tag.
+You can (and should!) add a description for each type and property. For an in-depth explanation of how to write good descriptions, see [Documenting the API specification](doc-comments-guide.md).
 
 ```ts
 class Foo {