TypeDoc注释标签大全：掌握50+JSDoc和TSDoc标签

TypeDoc注释标签大全：掌握50+JSDoc和TSDoc标签

【免费下载链接】typedoc Documentation generator for TypeScript projects. 项目地址: https://gitcode.com/gh_mirrors/ty/typedoc

TypeDoc是TypeScript项目的专业文档生成工具，支持50多种JSDoc和TSDoc注释标签，帮助开发者创建高质量的API文档。通过合理使用这些标签，你可以大幅提升代码的可读性和维护性，让团队成员快速理解你的代码设计意图。📚

TypeDoc标签分类详解

块级标签 (Block Tags)

块级标签用于标记文档的结构段落，它们与后续文本内容相关联：

@param - 描述函数参数，支持类型和默认值说明 @returns - 描述函数返回值类型和含义 @example - 提供代码使用示例，支持语法高亮 @remarks - 添加详细说明和补充信息 @see - 引用相关文档或外部资源 @since - 标记功能引入的版本号

修饰符标签 (Modifier Tags)

修饰符标签用于设置反射的特殊行为标志：

@public - 标记为公开API @private - 标记为私有API
@protected - 标记为受保护API @internal - 标记为内部使用 @deprecated - 标记已弃用的API

行内标签 (Inline Tags)

行内标签用于在段落文本中进行特殊标记：

@link - 创建内部或外部链接 @inheritDoc - 继承父类文档注释 @include - 包含外部文档内容

核心标签使用指南

@param标签详解

@param标签是函数文档中最常用的标签之一，用于详细描述每个参数的作用、类型和约束条件。通过合理的参数文档，可以帮助使用者正确调用函数并避免常见错误。

@returns标签最佳实践

@returns标签应该清晰说明函数的返回值类型、可能的返回值情况以及特殊返回值处理逻辑。对于可能返回多种类型的函数，需要详细描述每种情况。

@example标签高级用法

@example标签支持代码块的语法高亮，可以展示多种使用场景。建议为复杂函数提供多个使用示例，涵盖常见用例和边界情况。

标签配置与管理

TypeDoc支持通过tsdoc.json文件自定义支持的标签：

{
  "$schema": "https://developer.microsoft.com/en-us/json-schemas/tsdoc/v0/tsdoc.schema.json",
  "extends": ["typedoc/tsdoc.json"],
  "noStandardTags": false,
  "tagDefinitions": [
    {
      "tagName": "@customTag",
      "syntaxKind": "modifier"
    }
  ]
}

实用技巧与注意事项

1. 标签顺序 - 建议按照@param、@returns、@example、@remarks的顺序排列
2. 内容格式 - 保持文档格式的一致性，提高可读性
3. 版本管理 - 使用@since标签跟踪API的演进历史
4. 弃用处理 - 使用@deprecated标签时建议说明替代方案

通过掌握这些TypeDoc注释标签，你可以创建出专业级别的API文档，提升项目的整体质量和团队协作效率。💪

【免费下载链接】typedoc Documentation generator for TypeScript projects. 项目地址: https://gitcode.com/gh_mirrors/ty/typedoc