From 4110e8fc9befd032c30bfe24f0adc996d3574afa Mon Sep 17 00:00:00 2001 From: Timothee Guerin Date: Mon, 27 Nov 2023 17:17:35 -0800 Subject: [PATCH] Doc: Tweak to Doc comment doc (#2705) Remove naming of `TSDoc` and list available tags --------- Co-authored-by: Mark Cowlishaw --- .../docs-doc-comment_2023-11-27-23-52.json | 10 +++++ docs/language-basics/documentation.md | 39 ++++++++++++++----- packages/compiler/src/core/parser.ts | 2 +- 3 files changed, 41 insertions(+), 10 deletions(-) create mode 100644 common/changes/@typespec/compiler/docs-doc-comment_2023-11-27-23-52.json diff --git a/common/changes/@typespec/compiler/docs-doc-comment_2023-11-27-23-52.json b/common/changes/@typespec/compiler/docs-doc-comment_2023-11-27-23-52.json new file mode 100644 index 000000000..5945164bd --- /dev/null +++ b/common/changes/@typespec/compiler/docs-doc-comment_2023-11-27-23-52.json @@ -0,0 +1,10 @@ +{ + "changes": [ + { + "packageName": "@typespec/compiler", + "comment": "", + "type": "none" + } + ], + "packageName": "@typespec/compiler" +} \ No newline at end of file diff --git a/docs/language-basics/documentation.md b/docs/language-basics/documentation.md index d8ce3e780..89c7f3a1d 100644 --- a/docs/language-basics/documentation.md +++ b/docs/language-basics/documentation.md @@ -5,10 +5,19 @@ title: Documentation # Documentation -Documentation is crucial to any API. TypeSpec provides a number of ways to document your API using TSDoc doc comments and decorators. +Documentation is crucial to any API. TypeSpec provides a number of ways to document your API using doc comments and decorators. # Documenting APIs +There are 2 ways to document your API using TypeSpec: + +- `@doc` decorator +- `/** */` Doc comments + +The later has the advantage of being less intrusive to the spec. + +## `@doc` Decorator + ## `@doc` Decorator The `@doc` decorator can be used to attach documentation to most TypeSpec declarations. It most-commonly accepts a string argument that will be used as the documentation for the declaration. @@ -32,31 +41,43 @@ model Template { model A is Template ``` -## TSDoc Doc Comments +## Doc Comments -TSDoc doc comments are a standard way to document TypeScript code. They are supported by many IDEs and can be used to generate external documentation using tools like [TypeDoc](https://typedoc.org/). +You can annotate objects in your TypeSpec spec with doc comments. These comments will be considered the same as if they were attached using the `@doc` decorator and can be used to generate external documentation. -You can annotate objects in your TypeSpec spec with TSDoc doc comments. These comments will be considered the same as if they were attached using the `@doc` decorator and can be used to generate external documentation. +Doc comments starts with `/**` and continue until the closing `*/` is encountered. [Tags](#doc-comment-tags) can be used to provide additional documentation context. ```typespec /** * Get a widget. * @param widgetId The ID of the widget to retrieve. - * / -op @get create(@path widgetId: string): Widget | Error; + */ +op read(@path widgetId: string): Widget | Error; ``` This is functionally equivalent to: ```typespec @doc("Get a widget.") -op @get create( +op read( @doc("The ID of the widget to retrieve.") @path - widgetId: string): Widget | Error; + widgetId: string, +): Widget | Error; ``` -The benefit to using TSDoc doc comment syntax is that it keeps all of the documentation for a declaration in one place, making it easier to read and maintain. Additionally, it allows the generation of documentation using tools like TypeDoc without having to write a custom emitter to examine the `@doc` metadata. +The benefit to using doc comment syntax is that it keeps all of the documentation for a declaration in one place, making it easier to read and maintain. Additionally, it allows the generation of documentation using tools like TypeDoc without having to write a custom emitter to examine the `@doc` metadata. + +### Doc comment tags + +As shown in the previous example doc comments can use certain tags to document additional elements or provide different documentation context. + +| Tag | Description | Example | +| ----------------------- | --------------------------------- | --------------------------------------------------- | +| `@param` | Documents a parameter. | `@param widgetId The ID of the widget to retrieve.` | +| `@returns` | Documents the operation response. | `@returns The widget.` | +| `@template` | Document a template parameter | `@template T the resource type` | +| `@example` (unofficial) | Show examples | `@example \`model Foo {}\` ` | # Comments diff --git a/packages/compiler/src/core/parser.ts b/packages/compiler/src/core/parser.ts index 444dc4255..ed700f1d6 100644 --- a/packages/compiler/src/core/parser.ts +++ b/packages/compiler/src/core/parser.ts @@ -2411,7 +2411,7 @@ function createParser(code: string | SourceFile, options: ParseOptions = {}): Pa /** * Parses a documentation tag. * - * @see TypeSpec documentation docs + * @see TypeSpec documentation docs */ function parseDocTag(): DocTag { const pos = tokenPos();