求助：Dart Doc无法生成lib子文件夹的文档

问题现象 #

运行dart doc .或dart doc命令时，仅能生成lib/main.dart和lib/config/config.dart的文档，lib/src/model/wall_model.dart、lib/src/widgets/some.dart等子目录文件的文档无法生成。项目文件夹结构如下：

• lib > main.dart
• lib > src > model > wall_model.dart
• lib > src > widgets > some.dart

main.dart代码示例：

import 'package:photo_qc/src/screens/login_page.dart';

// common imports
import 'package:photo_qc/src/utils/common.dart';

/// App starts here at [main]
void main() async {
  /// Insures all widget bootstrapping
  WidgetsFlutterBinding.ensureInitialized();

  /// Creates HiveDB if not exists at [path]
  ///
  /// Links it with bloc architecture
  final Storage storage = await HydratedStorage.build(
    storageDirectory: await getApplicationDocumentsDirectory(),
  );

  /// Starts app
  ///
  /// Everything in [runZone] can access [HydratedBloc]
  HydratedBlocOverrides.runZoned(
    () => runApp(const LoginPage()),
    storage: storage,
  );
}

已确认代码符合Effective Dart规范，dart analyse或flutter analyse检测无问题。

原因分析 #

dartdoc的核心逻辑是生成公开API文档，只会扫描从库顶层入口文件公开导出的代码。如果src目录下的文件没有被顶层文件导出，dartdoc会默认忽略这些文件，这是dartdoc的设计特性，并非代码错误。

解决方法 #

1. 创建包顶层导出文件
   建议创建与包名同名的顶层文件（比如lib/photo_qc.dart），在其中公开导出src目录下需要生成文档的文件：

   // lib/photo_qc.dart
   export 'src/model/wall_model.dart';
   export 'src/widgets/some.dart';
   // 按需添加其他需要生成文档的src子目录文件
   

2. 直接在main.dart中导出（可选）
   若不想单独创建顶层文件，也可在lib/main.dart顶部添加导出语句，但更推荐用专门的顶层文件维护公开API：

   // 在main.dart开头添加
   export 'src/model/wall_model.dart';
   export 'src/widgets/some.dart';
   

3. 重新执行文档生成命令
   运行dart doc .，此时dartdoc会扫描被公开导出的src子目录文件，生成对应文档。

内容的提问来源于stack exchange，提问作者Akshat Tamrakar