Add readme info

Author: lcawl

docs/doc-comments-guide.md

@@ -58,7 +58,7 @@ export interface Request extends RequestBase {
 ([original source code](https://github.com/elastic/elasticsearch-specification/blob/main/specification/_global/rank_eval/RankEvalRequest.ts))
 
 For more information about the tags in this example (and other common tags such
-as `@deprecated` and `@doc_id`), refer to the [Modeling Guide](https://github.com/elastic/elasticsearch-specification/blob/main/docs/modeling-guide.md#additional-information).
+as `@deprecated` and `@ext_doc_id`), refer to the [Modeling Guide](https://github.com/elastic/elasticsearch-specification/blob/main/docs/modeling-guide.md#additional-information).
 
 ## Markup language
 
@@ -76,9 +76,9 @@ GFM also has implementations in most languages, meaning that code generators wil
 
 **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.
+In particular, doc comments are not the right place for tutorials or extended examples, which should be in dedicated documentation pages. To reduce the risk of broken links, use `@ext_doc_id` to implement a link to additional documentation. 
 
-API endpoints will also have a `@doc_url` JSDoc tag that links to that API's detailed documentation page.
+API endpoints can also have `@doc_id` or `@doc_url` JSDoc tags that enable clients to link to the API docs, for example.
 
 ### Multi-paragraph doc comments
 

docs/modeling-guide.md

@@ -598,37 +598,61 @@ class Foo {
 }
 ```
 
-#### `@doc_url`
+#### `@doc_id`
 
-The documentation url for the parameter or definition.
-If possible, use `@doc_id`.
+An identifier that can be used for generating the doc url in clients.
+The unique id/url pair must exist in `specification/_doc_ids/table.csv`.
+NOTE: This link is *not* included in the OpenAPI output.
 
 ```ts
-class Foo {
-  bar: string
-  /** @doc_url http://localhost:9200 */
-  baz?: string
-  faz: string
+/**
+ * @rest_spec_name api
+ * @doc_id foobar
+ */
+class Request {
+  ...
 }
 ```
 
-#### `@doc_id`
+```csv
+foobar,/guide/en/example
+```
+
+#### `@ext_doc_id`
 
-The documentation id that can be used for generating the doc url.
-You must add the id/url pair in `specification/_doc_ids/table.csv`.
+An identifier for a link.
+The unique id/url pair must exist in `specification/_doc_ids/table.csv`.
+NOTE: This link is included in the OpenAPI output.
 
 ```ts
 /**
- * @rest_spec_name api
- * @doc_id foobar
+ * @variants container
+ * @non_exhaustive
+ * @ext_doc_id query-dsl
  */
-class Request {
+export class QueryContainer {
   ...
 }
 ```
 
 ```csv
-foobar,/guide/en/example
+query-dsl,/guide/en/example
+```
+
+
+#### `@doc_url`
+
+The documentation url for the parameter or definition.
+To reduce the risk of broken links, use `@doc_id` instead.
+NOTE: This link is *not* included in the OpenAPI output.
+
+```ts
+class Foo {
+  bar: string
+  /** @doc_url http://localhost:9200 */
+  baz?: string
+  faz: string
+}
 ```
 
 #### `@doc_tag`