今天的文肯定会很水，但应该也会很好玩。

一、最简单最低标准的注释

一般要求实现 类、方法、参数、类型、返回值等的 TSDoc、JavaDoc、JSDoc 等规范的最简注释：

示例代码

/**
 * Http服务
 * @author Hamm.cn
 */
class Http {
  /**
   * 请求的URL
   */
  private url!: string

  /**
   * 创建Http实例
   * @param url URL
   * @returns Http实例
   */
  static init(url: string): Http{
    const http = new Http()
    http.url = url
    return http;
  }
}

实现效果

二、更规范的注释

接下来我们引入一些标准的注解来丰富一下注释，如弃用、重定向、链接等：

示例代码

/**
 * Http服务
 * @author Hamm.cn
 */
class Http {
  /**
   * 请求的URL
   */
  private url!: string

  /**
   * 初始化Http实例
   * @param url 请求的URL
   * @returns Http实例
   * @throws Error 格式错误的URL
   * @link https://developer.mozilla.org/zh-CN/docs/Web_mechanics/What_is_a_URL
   */
  static create(url: string): Http {
    // 返回一个Http实例
    const u = new URL(url)
    const http = new Http()
    http.url = u.href
    return http;
  }

  /**
   * 创建Http实例
   * @param url URL
   * @returns Http实例
   * @deprecated 此方法没有校验URL合法性，可能导致后续发送请求出现异常
   * @see create()
   * @link https://developer.mozilla.org/zh-CN/docs/Web_mechanics/What_is_a_URL
   */
  static init(url: string): Http{
    const http = new Http()
    http.url = url
    return http;
  }
}

实现效果

下图因为被标记了 @deprecated 而显示 init 方法被弃用，并显示了弃用的原因，以及通过 @see 推荐使用的新方法 create，通过 @link 显示了参考文档。

而且，如果调用了这类被弃用方法，调用的位置也会有相应的 删除线标记：

三、更美观的注释

众所周知？？？ Jetbrains 和 vscode 以及很多的IDE（或编辑器）的注释都是支持渲染部分 html 和 markdown 的。于是有了下面一些注释：

这里简单的通过标题字号来放大了需要调用方重点关注的事项，如方法名称、弃用的注释删除线、长URL渲染到超链接标签等：

示例代码

/**
 * Http服务
 * @author Hamm.cn
 */
class Http {
  /**
   * # 请求的URL
   */
  private url!: string

  /**
   * # 初始化Http实例
   * @param url 请求的URL
   * @returns Http实例
   * @throws Error 格式错误的URL
   * @link [MDN参考文档](https://developer.mozilla.org/zh-CN/docs/Web_mechanics/What_is_a_URL)
   */
  static create(url: string): Http {
    // 返回一个Http实例
    const u = new URL(url)
    const http = new Http()
    http.url = u.href
    return http;
  }

  /**
   * # ~~创建Http实例~~
   * @param url URL
   * @returns Http实例
   * @deprecated 此方法没有校验URL合法性，可能导致后续发送请求出现异常
   * @see create()
   * @link [MDN参考文档](https://developer.mozilla.org/zh-CN/docs/Web_mechanics/What_is_a_URL)
   */
  static init(url: string): Http{
    const http = new Http()
    http.url = url
    return http;
  }
}

实现效果

四、逐渐离谱的注释

通过 MarkDown 写一些调用的 demo 代码，像写文章一样把注释丰富一下，调用方不会再说不知道怎么调用了吧？

示例代码

/**
 * # Http服务
 * @author Hamm.cn
 */
class Http {
  /**
   * # 请求的URL
   */
  private url!: string

  /**
   * # 初始化Http实例
   * @param url 请求的URL
   * @returns Http实例
   * @throws Error 格式错误的URL
   * @link [MDN参考文档](https://developer.mozilla.org/zh-CN/docs/Web_mechanics/What_is_a_URL)
   * @example
   * - 初始化一个Http实例
   * - 设置请求数据类型
   * - 设置身份等Header头
   * - `get`/`post`/`put`/`delete`请求
   * 
   * ```typescript
   * const result = Http.create("https://hamm.cn")
   *                    .setContentType(ContentType.JSON)
   *                    .setHeader("Authorzation", "Bearer 123456")
   *                    .post(data)
   * ```
   */
  static create(url: string): Http {
    // 返回一个Http实例
    const u = new URL(url)
    const http = new Http()
    http.url = u.href
    return http;
  }
}

实现效果

五、更加离谱的注释

既然能用 Markdown，再加点 Emoji, 嘿嘿嘿嘿嘿～

Emoji 的皮注释

AirPower 提供的 AirDateTime.sleep()

AirPower 的 AirI18n 类

六、MarkDown是吧?

都玩到这里了，要不加点料？

你干嘛～

The End ~

今天水完了，收工～

皮归皮，更多的注释可以参考我们的开源项目：

Github: github.com/HammCn/AirP…

Gitee: gitee.com/air-power/A…

当然，也欢迎你阅读我的专栏：“用TypeScript写前端”。