什么是dartdoc_options.yaml文件？该如何创建这个配置文件？

1. 文件定义 #

dartdoc_options.yaml 是 Dart 生态体系中，专门给 dartdoc 文档生成工具使用的YAML格式配置文件，作用是自定义API文档的生成规则、展示效果、筛选逻辑等个性化设置。

注意：默认状态下运行 dartdoc 不需要该配置文件，工具会使用默认规则生成文档。如果你的运行环境提示必须存在该文件，一般是旧版本 dartdoc 限制、项目依赖有预设配置校验规则导致的。

2. 创建方法 #

直接在 Dart/Flutter 项目的根目录（和 pubspec.yaml 文件同级目录）新建名为 dartdoc_options.yaml 的文件即可，你可以根据需求填入配置项，以下是常用的基础配置参考：

dartdoc:
  # 文档输出路径
  output: doc/api
  # 排除不需要生成文档的目录/文件
  exclude:
    - test/**
    - example/**
  # 文档页面显示的项目名称
  name: 你的项目名称
  # 文档页面显示的项目描述
  description: 项目API接口说明文档
  # 是否展示未写文档注释的类/方法
  showUndocumentedCategories: true

3. 运行异常排查 #

• 创建空白配置文件后仍无法运行的，先执行 dart pub global activate dartdoc 将工具升级到最新版本后重试
• 可执行 dart doc --help 查看所有支持的配置参数和命令用法

内容的提问来源于stack exchange，提问作者Alessandro Antonio Del Gaudio