如何使用代码注释:关于JavaScript与TypeScript

简介: TSDoc是一种标准化TypeScript代码文档注释的规范,使不同工具能无干扰地提取内容。它包括多种标记,如@alpha、@beta等发布阶段标记;@decorator、@deprecated等功能标记;@defaultValue、@eventProperty等描述标记;@example、@experimental等示例与实验性标记;@inheritDoc、@internal等引用与内部标记;@label、@link等链接标记;@override、@sealed等修饰符标记;以及@packageDocumentation、@param、
  1. TSDoc:注释规范
    TSDoc 是一个标准化 TypeScript 代码中使用的文档注释的建议,以便不同的工具可以提取内容而不会被彼此的标记混淆。
    1.1 注释标记简表
    注释
    描述
    @alpha
    指定 API 项的发布阶段为“alpha”。它旨在用于 第三方开发者最终,但尚未发布。该工具可能会从 公开发布。
    @beta
    指定 API 项的发布阶段为“测试版”。它已通过实验性发布给第三方开发人员 为了收集反馈。
    @decorator
    ECMAScript 装饰器有时是一个重要的部分 的 API 协定。但是,今天TypeScript编译器不代表.d.ts输出文件中的装饰器 由 API 使用者使用。该标记提供了一种解决方法,允许将装饰器表达式括起来 在文档评论中。
    @deprecated
    此块标记表示不再支持 API 项,并且可能会在将来的版本中删除。 标记后跟一个描述推荐替代方案的句子。它递归应用 容器的成员。例如,如果一个类被弃用,那么它的所有成员也是如此。
    @defaultValue
    如果未显式分配值,则此块标记用于记录字段或属性的默认值。此标记只能与属于 TypeScript class 或 interface 成员的字段或属性一起使用。
    @eventProperty
    当应用于类或接口属性时,这表示该属性 返回事件处理程序可以附加到的事件对象。事件处理 API 是实现定义的,但通常属性返回类型是一个类 与成员如 addHandler() 和 removeHandler()。文档工具可以 在“Events”标题下显示此类属性,而不是通常的“Properties”标题。
    @example
    指示应作为示例演示如何使用 API 的文档部分。 它可能包括代码示例。
    @experimental
    与 @beta 相同的语义,但由不支持@alpha发布阶段的工具使用。
    @inheritDoc
    此内联标记用于通过从另一个 API 项复制 API 项的文档来自动生成该文档 接口项。内联标记参数包含对其他项的引用,该项可能是不相关的类, 甚至是从单独的 NPM 包导入。
    @internal
    指定不计划由第三方开发人员使用 API 项。该工具可能会修剪 公开发布的声明。在某些实现中,可能允许某些指定的包 使用内部 API 项,例如,因为包是同一产品的组件。
    @label
    内联 {@label} 标记用于标记声明,以便可以使用 TSDoc 声明引用表示法。
    @link
    {@link} 内联标记用于创建指向文档系统中其他页面或通用internet URLs的超链接。特别是,它支持引用API项的表达式。
    @override
    这个修饰符的语义类似于C#或Java中的override关键字。对于成员函数或属性,显式指示此定义重写(即重新定义)从基类继承的定义。基类定义通常会被标记为虚拟的。
    @packageDocumentation
    用于表示描述整个NPM包的文档注释(相对于属于该包的单个API项)。@packageDocumentation 注释位于 .d.ts 文件中,该文件充当包的入口点,它应该是在该文件中遇到的第一个/** 注释。包含 @packageDocumentation标签的注释不应该用于描述单个API项。
    @param
    用于记录函数参数。@param 标记后面是参数名,后面是连字符,再后面是描述。
    @privateRemarks
    启动不面向公众的其他文档内容的一部分。 工具必须从 API 参考网站(生成的
    .d.ts 文件)中省略整个部分, 以及包含内容的任何其他输出。
    @public
    指定 API 项的发布阶段为 “public”。已经正式发布给第三方开发者, 并且其签名保证稳定(例如,遵循语义版本控制规则)。
    @readonly
    此修饰符标记指示API项应该被记录为只读的,即使TypeScript类型系统可能另有指示。例如,假设一个类属性有一个setter函数,它总是抛出一个异常,说明该属性不能赋值;在这种情况下,可以添加 @readonly 修饰符,以便该属性在文档中显示为只读。
    @remarks
    API项目的主要文件被分成一个简短的“总结”部分,随后是一个更详细的“备注”部分。在文档网站上,索引页(例如显示类的成员)将只显示简短的摘要,而详细页(例如描述单个成员)将显示摘要,后跟备注。@remarks 块标记结束摘要部分,并开始文档注释的备注部分。
    @returns
    用于记录函数的返回值。
    @sealed
    这个修饰符的语义类似于C#或Java中的 sealed 关键字。对于类,指示子类不能从类继承。对于成员函数或属性,表示子类不能覆盖(即重定义)成员。
    @see
    用于生成对可能与 当前项目。
    @throws
    用于记录可能由函数或属性引发的异常类型。
    @typeParam
    用于记录通用参数。@typeParam 标记后面是参数名、连字符和说明。TSDoc解析器识别这种语法,并将它提取到DocParamBlock节点中。
    @virtual
    这个修饰符的语义类似于C#或Java中的 virtual 关键字。对于成员函数或属性,显式指示子类可以重写(即重定义)成员。
    1.2 标记用法详解
    本节整理和翻译自 TSDoc 规范官网
    1.2.1 @alpha
    指定 API 项的发布阶段为“alpha”。它旨在用于 第三方开发者最终,但尚未发布。该工具可能会从 公开发布。
    例如:
    /**
    • Represents a book in the catalog.
    • @public
      /
      export class Book {
      /*
    • The title of the book.
    • @alpha
      /
      public get title(): string;
      /*
    • The author of the book.
      /
      public get author(): string;
      };
      在这个例子中,Book.author从包含它的类继承了它的@public名称,而Book.title被标记为“alpha”。
      1.2.2 @beta
      指定 API 项的发布阶段为“测试版”。它已通过实验性发布给第三方开发人员 为了收集反馈。
      例如:
      /*
    • Represents a book in the catalog.
    • @public
      /
      export class Book {
      /*
    • The title of the book.
    • @beta
      /
      public get title(): string;
      /*
    • The author of the book.
      /
      public get author(): string;
      };
      在这个例子中,Book.author从包含它的类继承了它的@public名称,而Book.title被标记为“beta”。
      1.2.3 @decorator
      ECMAScript装饰器 有时是API契约的重要组成部分。然而,今天TypeScript编译器并不表示API消费者使用的. d.ts输出文件中的装饰器。@decorator标签提供了一种变通方法,允许在doc注释中引用decorator表达式。
      例如:
      class Book {
      /*
    • The title of the book.
    • @decorator @jsonSerialized
    • @decorator @jsonFormat(JsonFormats.Url)
      /
      @jsonSerialized
      @jsonFormat(JsonFormats.Url)
      public website: string;
      }
      1.2.4 @deprecated
      此块标记表示不再支持 API 项,并且可能会在将来的版本中删除。 标记后跟一个描述推荐替代方案的句子。它递归应用 容器的成员。例如,如果一个类被弃用,那么它的所有成员也是如此。
      例如:
      /*
    • The base class for controls that can be rendered.
      *
    • @deprecated Use the new {@link Control} base class instead.
      /
      export class VisualControl {
      . . .
      }
      1.2.5 @defaultValue
      如果未显式分配值,则此块标记用于记录字段或属性的默认值。此标记只能与属于 TypeScript class 或 interface 成员的字段或属性一起使用。
      例如:
      enum WarningStyle {
      DialogBox,
      StatusMessage,
      LogOnly
      }
      interface IWarningOptions {
      /*
    • Determines how the warning will be displayed.
      *
    • @remarks
    • See {@link WarningStyle| the WarningStyle enum} for more details.
      *
    • @defaultValue WarningStyle.DialogBox
      /
      warningStyle: WarningStyle;
      /*
    • Whether the warning can interrupt a user's current activity.
    • @defaultValue
    • The default is true unless
    • WarningStyle.StatusMessage was requested.
      /
      cancellable?: boolean;
      /*
    • The warning message
      /
      message: string;
      }
      1.2.6 @eventProperty
      当应用于类或接口属性时,这表示该属性 返回事件处理程序可以附加到的事件对象。事件处理 API 是实现定义的,但通常属性返回类型是一个类 与成员如 addHandler() 和 removeHandler()。文档工具可以 在“Events”标题下显示此类属性,而不是通常的“Properties”标题。
      例如:
      class MyClass {
      /*
      • This event is fired whenever the application navigates to a new page.
      • @eventProperty
        /
        public readonly navigatedEvent: FrameworkEvent;
        }
        1.2.7 @example
        指示应作为示例演示如何使用 API 的文档部分。 它可能包括代码示例。
        例如:
        /*
    • Adds two numbers together.
    • @example
    • Here's a simple example:
    • ```
    • // Prints "2":
    • console.log(add(1,1));
    • ```
    • @example
    • Here's an example with negative numbers:
    • ```
    • // Prints "0":
    • console.log(add(1,-1));
    • ```
      /
      export function add(x: number, y: number): number {
      }
      例如:
      /*
    • Parses a JSON file.
      *
    • @param path - Full path to the file.
    • @returns An object containing the JSON data.
      *
    • @example Parsing a basic JSON file
      *
    • Contents of file.json

    • ```json
    • {
    • "exampleItem": "text"
    • }
    • ```
      *
    • Usage

    • ```ts
    • const result = parseFile("file.json");
    • ```
      *
    • Result

    • ```ts
    • {
    • exampleItem: 'text',
    • }
    • ```
      /
      1.2.8 @experimental
      例如:
      /*
    • Represents a book in the catalog.
    • @public
      /
      export class Book {
      /*
    • The title of the book.
    • @experimental
      /
      public get title(): string;
      /*
    • The author of the book.
      /
      public get author(): string;
      };
      在这个例子中,Book.author从包含它的类继承了它的@public名称,而Book.title被标记为“experimental”。
      1.2.9 @inheritDoc
      这个内联标签用于通过从另一个API项复制来自动生成一个API项的文档。inline tag参数包含对另一个项目的引用,它可能是一个不相关的类,甚至是从一个单独的NPM包导入的。
      注意:声明引用的符号尚未最终确定。
      什么被复制
      @inheritDoc 标记不会复制整个注释体。仅复制以下组件:
      • 摘要部分
      • @remarks块
      • @params块
      • @typeParam块
      • @returns块
      其他标签(如 @defaultValue 或 @example )不会被复制,需要显式包含在 @inheritDoc 标签之后。当指定了@inheritDoc标记时,不能在注释中指定summary部分和 @remarks 部分。
      例如:
      import { Serializer } from 'example-library';
      /*
    • An interface describing a widget.
    • @public
      /
      export interface IWidget {
      /*
    • Draws the widget on the display surface.
    • @param x - the X position of the widget
    • @param y - the Y position of the widget
      /
      public draw(x: number, y: number): void;
      }
      /** @public
      /
      export class Button implements IWidget {
      / {@inheritDoc IWidget.draw} */
      public draw(x: number, y: number): void {
      . . .
      }
      /
    • {@inheritDoc example-library#Serializer.writeFile}
    • @deprecated Use {@link example-library#Serializer.writeFile} instead.
      /
      public save(): void {
      . . .
      }
      }
      1.2.10 @internal
      指定不计划由第三方开发人员使用 API 项。该工具可能会修剪 公开发布的声明。在某些实现中,可能允许某些指定的包 使用内部 API 项,例如,因为包是同一产品的组件。
      例如:
      /*
    • Represents a book in the catalog.
    • @public
      /
      export class Book {
      /*
    • The title of the book.
    • @internal
      /
      public get _title(): string;
      /*
    • The author of the book.
      /
      public get author(): string;
      };
      1.2.11 @label
      内联 {@label} 标记用于标记声明,以便可以使用 TSDoc 声明引用表示法。
      {@label}符号尚未最终确定。
      例如:
      export interface Interface {
      /*
    • Shortest name: {@link InterfaceL1.(:STRING_INDEXER)}
    • Full name: {@link (InterfaceL1:interface).(:STRING_INDEXER)}
      *
    • {@label STRING_INDEXER}
      */

/**

  • Shortest name: {@link InterfaceL1.(:NUMBER_INDEXER)}
  • Full name: {@link (InterfaceL1:interface).(:NUMBER_INDEXER)}
    *
  • {@label NUMBER_INDEXER}
    */

/**

  • Shortest name: {@link InterfaceL1.(:FUNCTOR)}
  • Full name: {@link (InterfaceL1:interface).(:FUNCTOR)}
    *
  • {@label FUNCTOR}
    /
    (source: string, subString: string): boolean;
    /*
  • Shortest name: {@link InterfaceL1.(:CONSTRUCTOR)}
  • Full name: {@link (InterfaceL1:interface).(:CONSTRUCTOR)}
    *
  • {@label CONSTRUCTOR}
    /
    new (hour: number, minute: number);
    }
    1.2.12 @link
    {@link} 内联标记用于创建指向文档系统中其他页面或通用internet URLs的超链接。特别是,它支持引用API项的表达式。
    声明引用的符号尚未最终确定。
    例如:
    /*
    • Let's learn about the {@link} tag.
      *
    • @remarks
      *
    • Links can point to a URL: {@link https://github.com/microsoft/tsdoc}
      *
    • Links can point to an API item: {@link Button}
      *
    • You can optionally include custom link text: {@link Button | the Button class}
      *
    • Suppose the Button class is part of an external package. In that case, we
    • can include the package name when referring to it:
      *
    • {@link my-control-library#Button | the Button class}
      *
    • The package name can include an NPM scope and import path:
      *
    • {@link @microsoft/my-control-library/lib/Button#Button | the Button class}
      *
    • The TSDoc standard calls this notation a "declaration reference". The notation supports
    • references to many different kinds of TypeScript declarations. This notation was originally
    • designed for use in {@link} and {@inheritDoc} tags, but you can also use it in your
    • own custom tags.
      *
    • For example, the Button can be part of a TypeScript namespace:
      *
    • {@link my-control-library#controls.Button | the Button class}
      *
    • We can refer to a member of the class:
      *
    • {@link controls.Button.render | the render() method}
      *
    • If a static and instance member have the same name, we can use a selector to distinguish them:
      *
    • {@link controls.Button.(render:instance) | the render() method}
      *
    • {@link controls.Button.(render:static) | the render() static member}
      *
    • This is also how we refer to the class's constructor:
      *
    • {@link controls.(Button:constructor) | the class constructor}
      *
    • Sometimes a name has special characters that are not a legal TypeScript identifier:
      *
    • {@link restProtocol.IServerResponse."first-name" | the first name property}
      *
    • Here is a fairly elaborate example where the function name is an ECMAScript 6 symbol,
    • and it's an overloaded function that uses a label selector (defined using the {@label}
    • TSDoc tag):
      *
    • {@link my-control-library#Button.([UISymbols.toNumberPrimitive]:OVERLOAD_1)
    • | the toNumberPrimitive() static member}
      *
    • See the TSDoc spec for more details about the "declaration reference" notation.
      /
      1.2.13 @override
      这个修饰符的语义类似于C#或Java中的override关键字。对于成员函数或属性,显式指示此定义重写(即重新定义)从基类继承的定义。基类定义通常会被标记为虚拟的。
      文档工具可以强制一致地应用@virtual、@override和/或@sealed修饰符,但是这不是TSDoc标准所要求的。
      例如:
      class Base {
      /** @virtual
      /
      public render(): void {
      }
      / @sealed */
      public initialize(): void {
      }
      }
      class Child extends Base {
      /
      @override /
      public render(): void;
      }
      1.2.14 @packageDocumentation
      用于表示描述整个NPM包的文档注释(相对于属于该包的单个API项)。@packageDocumentation 注释位于
      .d.ts文件中,该文件充当包的入口点,它应该是在该文件中遇到的第一个 / 注释。包含 @packageDocumentation 标签的注释不应该用于描述单个API项。
      例如:
      // Copyright (c) Example Company. All rights reserved. Licensed under the MIT license.
      /
    • A library for building widgets.
      *
    • @remarks
    • The widget-lib defines the {@link IWidget} interface and {@link Widget} class,
    • which are used to build widgets.
      *
    • @packageDocumentation
      /
      /*
    • Interface implemented by all widgets.
    • @public
      /
      export interface IWidget {
      /*
  • Draws the widget on the screen.
    /
    render(): void;
    }
    1.2.15 @param
    用于记录函数参数。@param 标记后面是参数名,后面是连字符,再后面是描述。
    例如:
    /*
    • Returns the average of two numbers.
      *
    • @remarks
    • This method is part of the {@link core-library#Statistics | Statistics subsystem}.
      *
    • @param x - The first input number
    • @param y - The second input number
    • @returns The arithmetic mean of x and y
      *
    • @beta
      /
      function getAverage(x: number, y: number): number {
      return (x + y) / 2.0;
      }
      1.2.16 @privateRemarks
      启动不面向公众的其他文档内容的一部分。 工具必须从 API 参考网站(生成的
      .d.ts 文件)中省略整个部分, 以及包含内容的任何其他输出。
      例如:
      /**
    • The summary section should be brief. On a documentation web site,
    • it will be shown on a page that lists summaries for many different
    • API items. On a detail page for a single item, the summary will be
    • shown followed by the remarks section (if any).
      *
    • @remarks
      *
    • The main documentation for an API item is separated into a brief
    • "summary" section optionally followed by an @remarks block containing
    • additional details.
      *
    • @privateRemarks
      *
    • The @privateRemarks tag starts a block of additional commentary that is not meant
    • for an external audience. A documentation tool must omit this content from an
    • API reference web site. It should also be omitted when generating a normalized
    • .d.ts file. /
      1.2.17 @public
      指定 API 项的发布阶段为“public”。已经正式发布给第三方开发者, 并且其签名保证稳定(例如,遵循语义版本控制规则)。
      例如:
      /**
    • Represents a book in the catalog.
    • @public
      /
      export class Book {
      /*
  • The title of the book.
  • @internal
    /
    public get _title(): string;
    /*
  • The author of the book.
    /
    public get author(): string;
    };
    1.2.18 @readonly
    此修饰符标记指示 API 项应记录为只读,即使 TypeScript 类型系统可能另有指示。例如,假设一个类属性有一个 setter 函数,该函数始终 引发异常,说明无法分配属性;在这种情况下,@readonly 修饰符 可以添加,以便属性在文档中显示为只读。
    例如:
    export class Book {
    /*
  • Technically property has a setter, but for documentation purposes it should
  • be presented as readonly.
  • @readonly
    /
    public get title(): string {
    return this._title;
    }
    public set title(value: string) {
    throw new Error('This property is read-only!');
    }
    }
    1.2.19 @remarks
    API项目的主要文件被分成一个简短的“总结”部分,随后是一个更详细的“备注”部分。在文档网站上,索引页(例如显示类的成员)将只显示简短的摘要,而详细页(例如描述单个成员)将显示摘要,后跟备注。@remarks 块标记结束摘要部分,并开始文档注释的备注部分。
    例如:
    //代码效果参考:https://www.xx-ph.com/sitemap/post.html
    /*
    • The summary section should be brief. On a documentation web site,
    • it will be shown on a page that lists summaries for many different
    • API items. On a detail page for a single item, the summary will be
    • shown followed by the remarks section (if any).
      *
    • @remarks
      *
    • The main documentation for an API item is separated into a brief
    • "summary" section optionally followed by an @remarks block containing
    • additional details.
      *
    • @privateRemarks
      *
    • The @privateRemarks tag starts a block of additional commentary that is not meant
    • for an external audience. A documentation tool must omit this content from an
    • API reference web site. It should also be omitted when generating a normalized
    • .d.ts file. /
相关文章
|
14天前
|
编解码 前端开发 JavaScript
javascript检测网页缩放演示代码
javascript检测网页缩放演示代码
|
16天前
|
Web App开发 JavaScript 前端开发
添加浮动按钮点击滚动到网页底部的纯JavaScript演示代码 IE9、11,Maxthon 1.6.7,Firefox30、31,360极速浏览器7.5.3.308下测试正常
添加浮动按钮点击滚动到网页底部的纯JavaScript演示代码 IE9、11,Maxthon 1.6.7,Firefox30、31,360极速浏览器7.5.3.308下测试正常
|
17天前
|
存储 JavaScript 前端开发
webSocket+Node+Js实现在线聊天(包含所有代码)
文章介绍了如何使用WebSocket、Node.js和JavaScript实现在线聊天功能,包括完整的前端和后端代码示例。
76 0
|
1天前
|
JavaScript 前端开发 UED
网站内容禁止复制的js代码
【10月更文挑战第2天】
|
2天前
|
JavaScript 前端开发 安全
探索Deno:新时代的JavaScript/TypeScript运行时
【10月更文挑战第1天】Deno是由Node.js创始人Ryan Dahl发起的JavaScript/TypeScript运行时,基于V8引擎,旨在提供安全、现代的开发环境。其核心优势包括默认安全性、内置TypeScript支持、统一的运行时及现代化API。Deno采用细粒度权限系统和ES模块系统,并提供内置测试与调试工具。尽管生态系统仍在发展中,学习曲线和兼容性问题存在,但Deno凭借其先进特性正逐渐成为开发领域的有力竞争者。
|
1天前
|
JavaScript 前端开发
电话号码正则表达式 代码 javascript+html,JS正则表达式判断11位手机号码
电话号码正则表达式 代码 javascript+html,JS正则表达式判断11位手机号码
|
13天前
|
存储 JavaScript 前端开发
改进JavaScript代码,给水果有序赋色
改进JavaScript代码,给水果有序赋色
|
15天前
|
存储 JSON JavaScript
JavaScript帮我编写快递自动分拣的代码,区分省份市区县城乡镇
JavaScript帮我编写快递自动分拣的代码,区分省份市区县城乡镇在JavaScript中编写一个用于快递自动分拣的代码,区分省份、市区、县、城乡镇,通常意味着你需要一个数据结构来存储这些地理区域的信息,并编写逻辑来根据快递地址中的信息将其分配到正确的分类中。 这里,我将提供一个简化的示例,说明如何使用JavaScript对象和函数来实现这一功能。请注意,这个示例是高度简化的,并且假设你已经有了某种方式(如正则表达式或API调用)来从快递地址中提取省份、市区、县等信息。 ----------------------------------- ©著作权归作者所有:来自51CTO博客作者goS
|
16天前
|
JavaScript 前端开发 Python
python执行js代码
本文档详细介绍如何安装Node.js环境及PyExecJS库,并提供示例代码展示其功能。首先,通过指定链接安装Node.js,安装完毕后可在命令行中输入`node --version`来验证安装是否成功。接着,使用`pip install PyExecJS`安装PyExecJS库,该库允许Python程序执行JavaScript代码。文档还提供了多个示例代码,展示了如何在Python环境中执行和编译JavaScript代码,并可以选择特定的JavaScript运行时环境,如Node.js或JScript。最后,通过具体案例展示了PyExecJS的功能与使用方法。
17 3
|
4天前
|
数据采集 JavaScript 前端开发
JavaScript中通过array.filter()实现数组的数据筛选、数据清洗和链式调用,JS中数组过滤器的使用详解(附实际应用代码)
JavaScript中通过array.filter()实现数组的数据筛选、数据清洗和链式调用,JS中数组过滤器的使用详解(附实际应用代码)