From c1526ccae917d3e81fc7240a690e43c57a2b9ae8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Istv=C3=A1n=20Zolt=C3=A1n=20Szab=C3=B3?= Date: Tue, 12 Aug 2025 18:11:05 +0200 Subject: [PATCH 1/4] Adds links that point to the API contrib guidelines to repo docs. --- README.md | 4 ++++ docs/add-new-api.md | 4 ++++ docs/doc-comments-guide.md | 4 +++- docs/modeling-guide.md | 2 +- docs/schema-structure.md | 2 +- 5 files changed, 13 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index d6b240f5f0..3715fc37e3 100644 --- a/README.md +++ b/README.md @@ -83,6 +83,10 @@ An interactive viewer for the Elasticsearch specification is available See [CONTRIBUTING.md](./CONTRIBUTING.md) +Refer to the +[Contributie to Elastic API docs](https://www.elastic.co/docs/extend/contribute/api-docs/) +for more details about the API documentation guidelines. + ## Make Targets ``` diff --git a/docs/add-new-api.md b/docs/add-new-api.md index 5b43e77804..c12f7351a9 100644 --- a/docs/add-new-api.md +++ b/docs/add-new-api.md @@ -5,6 +5,10 @@ in this repository, or we do have an endpoint definition in [`/specification/_js but we don't have a type definition for it. In this document you will see how to add a new endpoint and how to add a new endpoint definition. +Refer to the +[API docs contribution guidelines](https://www.elastic.co/docs/extend/contribute/api-docs/) +to learn more about how to craft great docs for your API. + ## How to add a new endpoint Add a new endpoint is straightforward, you only need to copy-paste the json rest-api-spec definition diff --git a/docs/doc-comments-guide.md b/docs/doc-comments-guide.md index a8775a49fc..7bde712d14 100644 --- a/docs/doc-comments-guide.md +++ b/docs/doc-comments-guide.md @@ -5,7 +5,7 @@ A specification is not only about formalizing data structures, it's also about e 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. 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). +Refer to the [API docs contribution guidelines](https://www.elastic.co/docs/extend/contribute/api-docs/guidelines) to learn more about how to create great documentation for your API. > [!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. @@ -76,6 +76,8 @@ GFM also has implementations in most languages, meaning that code generators wil ## Structuring a doc-comment +For guidelines of how to write great doc-comments, refer to the [Contribute to API docs](https://www.elastic.co/docs/extend/contribute/api-docs/guidelines#write-descriptions) page. + ### 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! diff --git a/docs/modeling-guide.md b/docs/modeling-guide.md index 8f0ea182c7..31507a346f 100644 --- a/docs/modeling-guide.md +++ b/docs/modeling-guide.md @@ -9,7 +9,7 @@ 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. +Refer to the [API docs contribution guidelines](https://www.elastic.co/docs/extend/contribute/api-docs/) to add documentation to types and fields. ### Dictionary diff --git a/docs/schema-structure.md b/docs/schema-structure.md index 8cb5e312ed..22ad67cb1f 100644 --- a/docs/schema-structure.md +++ b/docs/schema-structure.md @@ -9,7 +9,7 @@ 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, +Refer to the [API docs contributon guidelines](https://www.elastic.co/docs/extend/contribute/api-docs/) to add documentation to types and fields, and to the [modeling guide](modeling-guide.md) to learn how to model the different types. You can find the schema representing all APIs and types in the [output folder](output/schema/schema.json). From 2113a74cea39f4805a4fd3569e30fd5df27fa409 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Istv=C3=A1n=20Zolt=C3=A1n=20Szab=C3=B3?= Date: Wed, 13 Aug 2025 09:49:40 +0200 Subject: [PATCH 2/4] Apply suggestions from code review Co-authored-by: Quentin Pradet --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 3715fc37e3..f5d4ae40a4 100644 --- a/README.md +++ b/README.md @@ -84,7 +84,7 @@ An interactive viewer for the Elasticsearch specification is available See [CONTRIBUTING.md](./CONTRIBUTING.md) Refer to the -[Contributie to Elastic API docs](https://www.elastic.co/docs/extend/contribute/api-docs/) +[Contribute to Elastic API docs](https://www.elastic.co/docs/extend/contribute/api-docs/) for more details about the API documentation guidelines. ## Make Targets From c23a6d3064b424650642b090e6f1fd9f37e74737 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Istv=C3=A1n=20Zolt=C3=A1n=20Szab=C3=B3?= Date: Wed, 13 Aug 2025 10:07:34 +0200 Subject: [PATCH 3/4] Addresses feedback. --- README.md | 2 ++ docs/add-new-api.md | 5 ++--- docs/modeling-guide.md | 2 +- docs/schema-structure.md | 5 ++++- 4 files changed, 9 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 3715fc37e3..0ed78d68fb 100644 --- a/README.md +++ b/README.md @@ -18,6 +18,8 @@ The repository has the following structure: This JSON representation is formally defined by [a set of TypeScript definitions (a meta-model)](./compiler/src/model/metamodel.ts) that also explains the various properties and their values. +> [!TIP] +> To learn more about how to write docs specifically for our [API references](https://www.elastic.co/docs/api/), refer to our [contribution guide](https://www.elastic.co/docs/extend/contribute/api-docs/). ## Prepare the environment diff --git a/docs/add-new-api.md b/docs/add-new-api.md index c12f7351a9..08ff49234a 100644 --- a/docs/add-new-api.md +++ b/docs/add-new-api.md @@ -5,9 +5,8 @@ in this repository, or we do have an endpoint definition in [`/specification/_js but we don't have a type definition for it. In this document you will see how to add a new endpoint and how to add a new endpoint definition. -Refer to the -[API docs contribution guidelines](https://www.elastic.co/docs/extend/contribute/api-docs/) -to learn more about how to craft great docs for your API. +> [!TIP] +> To learn more about how to write docs specifically for our [API references](https://www.elastic.co/docs/api/), refer to our [contribution guide](https://www.elastic.co/docs/extend/contribute/api-docs/). ## How to add a new endpoint diff --git a/docs/modeling-guide.md b/docs/modeling-guide.md index 31507a346f..8f0ea182c7 100644 --- a/docs/modeling-guide.md +++ b/docs/modeling-guide.md @@ -9,7 +9,7 @@ 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 [API docs contribution guidelines](https://www.elastic.co/docs/extend/contribute/api-docs/) to add documentation to types and fields. +Refer to the [documentation guide](doc-comments-guide.md) to add documentation to types and fields. ### Dictionary diff --git a/docs/schema-structure.md b/docs/schema-structure.md index 22ad67cb1f..e43cfe4067 100644 --- a/docs/schema-structure.md +++ b/docs/schema-structure.md @@ -9,9 +9,12 @@ 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 [API docs contributon guidelines](https://www.elastic.co/docs/extend/contribute/api-docs/) to add documentation to types and fields, +Refer to the [documentation guide](doc-comments-guide.md) to add documentation to types and fields, and to the [modeling guide](modeling-guide.md) to learn how to model the different types. +> [!TIP] +> To learn more about how to write docs specifically for our [API references](https://www.elastic.co/docs/api/), refer to our [contribution guide](https://www.elastic.co/docs/extend/contribute/api-docs/). + You can find the schema representing all APIs and types in the [output folder](output/schema/schema.json). The schema is structured as follows: From ba9eee814ba55712f58639e3b5423cdb9ef233b6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Istv=C3=A1n=20Zolt=C3=A1n=20Szab=C3=B3?= Date: Tue, 19 Aug 2025 13:57:07 +0200 Subject: [PATCH 4/4] Apply suggestions from code review Co-authored-by: Quentin Pradet --- README.md | 2 +- docs/add-new-api.md | 2 +- docs/doc-comments-guide.md | 4 ++-- docs/schema-structure.md | 2 +- 4 files changed, 5 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 9ad1bf2a70..20c1d7a727 100644 --- a/README.md +++ b/README.md @@ -19,7 +19,7 @@ This JSON representation is formally defined by [a set of TypeScript definitions that also explains the various properties and their values. > [!TIP] -> To learn more about how to write docs specifically for our [API references](https://www.elastic.co/docs/api/), refer to our [contribution guide](https://www.elastic.co/docs/extend/contribute/api-docs/). +> To learn more about how to write docs specifically for our [API references](https://www.elastic.co/docs/api/), refer to the [Contribute to Elastic API docs](https://www.elastic.co/docs/extend/contribute/api-docs/). ## Prepare the environment diff --git a/docs/add-new-api.md b/docs/add-new-api.md index e87e2f7a66..a124f4e47d 100644 --- a/docs/add-new-api.md +++ b/docs/add-new-api.md @@ -6,7 +6,7 @@ but we don't have a type definition for it. In this document you will see how to add a new endpoint and how to add a new endpoint definition. > [!TIP] -> To learn more about how to write docs specifically for our [API references](https://www.elastic.co/docs/api/), refer to our [contribution guide](https://www.elastic.co/docs/extend/contribute/api-docs/). +> To learn more about how to write docs specifically for our [API references](https://www.elastic.co/docs/api/), refer to the [Contribute to Elastic API docs](https://www.elastic.co/docs/extend/contribute/api-docs/). ## How to add a new endpoint diff --git a/docs/doc-comments-guide.md b/docs/doc-comments-guide.md index 7bde712d14..1f33aa1f4b 100644 --- a/docs/doc-comments-guide.md +++ b/docs/doc-comments-guide.md @@ -5,7 +5,7 @@ A specification is not only about formalizing data structures, it's also about e 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. The first phrase is used as the mandatory operation summary in the OpenAPI document. -Refer to the [API docs contribution guidelines](https://www.elastic.co/docs/extend/contribute/api-docs/guidelines) to learn more about how to create great documentation for your API. +Refer to the [Elastic API docs contribution guidelines](https://www.elastic.co/docs/extend/contribute/api-docs/guidelines) to learn more about how to create great documentation for your API. > [!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. @@ -76,7 +76,7 @@ GFM also has implementations in most languages, meaning that code generators wil ## Structuring a doc-comment -For guidelines of how to write great doc-comments, refer to the [Contribute to API docs](https://www.elastic.co/docs/extend/contribute/api-docs/guidelines#write-descriptions) page. +For guidelines of how to write great doc-comments, refer to the [Contribute to Elastic API docs](https://www.elastic.co/docs/extend/contribute/api-docs/guidelines#write-descriptions) page. ### Terseness diff --git a/docs/schema-structure.md b/docs/schema-structure.md index e43cfe4067..dba3005f34 100644 --- a/docs/schema-structure.md +++ b/docs/schema-structure.md @@ -13,7 +13,7 @@ Refer to the [documentation guide](doc-comments-guide.md) to add documentation t and to the [modeling guide](modeling-guide.md) to learn how to model the different types. > [!TIP] -> To learn more about how to write docs specifically for our [API references](https://www.elastic.co/docs/api/), refer to our [contribution guide](https://www.elastic.co/docs/extend/contribute/api-docs/). +> To learn more about how to write docs specifically for our [API references](https://www.elastic.co/docs/api/), refer to the [Contribute to Elastic API docs](https://www.elastic.co/docs/extend/contribute/api-docs/). You can find the schema representing all APIs and types in the [output folder](output/schema/schema.json). The schema is structured as follows: