参数文档自动换行功能

问题描述

在生成 Retrofit API 代码时，参数的文档注释可能会非常长，特别是包含枚举值列表的参数。这会导致单行注释超过 80 字符的 lint 限制。

示例问题

/// - solutionSemesterEnum: 备 注:解决方案学期阶段枚举 初一上上半期 71, 初一上下半期 72, 初一下上半期 73, 初一下下半期 74, 初二上上半期 81, 初二上下半期 82, 初二下上半期 83, 初二下下半期 84, 初三上上半期 91, 初三上下半期 92, 初三下上半期 93, 初三下下半期 94, 高一上上半期 101, 高一上下半期 102, 高一下上半期 103, 高一下下半期 104, 高二上上半...

这行注释超过了 80 字符限制，会触发 lint 错误。

解决方案

实现了智能的参数文档换行功能，自动将超长的参数注释分成多行，每行不超过 76 字符（80 - /// 的长度）。

换行规则

第一行: 包含参数名和描述的开始部分
- 格式: - paramName: description...
续行: 使用两个空格缩进
- 格式: description continued...
断点选择: 优先在以下字符处断行
- 空格
- 逗号 , 和 ，
- 顿号 、
- 分号 ; 和 ；
- 竖线 |
- 斜杠 /
断点位置:
- 在不超过最大长度的前提下，尽可能靠后
- 至少要超过最大长度的 50%，避免断点太靠前

修复后的效果

/// - solutionSemesterEnum: 备 注:解决方案学期阶段枚举 初一上上半期 71, 初一上下半期 72, 初一下上半期 73,
///   初一下下半期 74, 初二上上半期 81, 初二上下半期 82, 初二下上半期 83, 初二下下半期 84, 初三上上半期 91, 初三上下半期
///   92, 初三下上半期 93, 初三下下半期 94, 高一上上半期 101, 高一上下半期 102, 高一下上半期 103, 高一下下半期 104,
///   高二上上半期 111

每行都不超过 76 字符，符合 lint 规则。

实现细节

核心函数

文件: lib/generators/retrofit_api/api_template_data.dart

/// 将参数文档行拆分为多行，确保每行不超过80字符
/// 专门处理 "- paramName: description" 格式的参数文档
List<String> _wrapParamDocLine(String paramDoc) {
  const maxLength = 76; // 80 - '/// '.length
  
  // 1. 检查是否需要换行
  if (paramDoc.length <= maxLength) {
    return [paramDoc];
  }

  // 2. 提取参数名和描述
  final match = RegExp(r'^- ([^:]+): (.+)$').firstMatch(paramDoc);
  if (match == null) {
    return _wrapDocLine(paramDoc); // 使用通用换行方法
  }
  
  final paramName = match.group(1)!;
  final description = match.group(2)!;
  final firstLinePrefix = '- $paramName: ';
  const continuationPrefix = '  ';
  
  // 3. 分行处理
  final lines = <String>[];
  var remaining = description;
  var isFirstLine = true;
  
  while (remaining.isNotEmpty) {
    final currentPrefix = isFirstLine ? firstLinePrefix : continuationPrefix;
    final currentMaxLength = maxLength - currentPrefix.length;
    
    if (remaining.length <= currentMaxLength) {
      lines.add(currentPrefix + remaining);
      break;
    }
    
    // 4. 寻找最佳断点
    var breakPoint = currentMaxLength;
    final breakChars = [' ', ',', '，', '、', ';', '；', '|', '/'];
    var bestIdx = -1;
    
    for (final ch in breakChars) {
      final idx = remaining.lastIndexOf(ch, currentMaxLength);
      if (idx > bestIdx && idx > currentMaxLength * 0.5) {
        bestIdx = idx;
      }
    }
    
    if (bestIdx >= 0) {
      breakPoint = bestIdx + 1;
    }
    
    final lineContent = remaining.substring(0, breakPoint).trim();
    lines.add(currentPrefix + lineContent);
    remaining = remaining.substring(breakPoint).trim();
    isFirstLine = false;
  }
  
  return lines;
}

调用位置

在 _buildDocLines 方法中，生成参数文档时调用:

if (paramsWithDescription.isNotEmpty) {
  lines
    ..add('')
    ..add('参数:');
  for (final param in paramsWithDescription) {
    final commentParts = <String>[];
    if (param.description.isNotEmpty) {
      commentParts.add(StringUtils.cleanDescription(param.description));
    }
    if (param.defaultValue != null) {
      commentParts.add('默认值: ${param.defaultValue}');
    }
    final paramDoc = '- ${param.name}: ${commentParts.join(' - ')}';
    // 使用改进的换行方法，处理参数文档
    lines.addAll(_wrapParamDocLine(paramDoc));
  }
}

测试

测试文件: test/param_doc_wrap_test.dart

运行测试:

dart test test/param_doc_wrap_test.dart

测试覆盖:

✅ 短参数文档不换行
✅ 长参数文档自动换行
✅ 在逗号处断行
✅ 在中文标点处断行
✅ 每行长度不超过 76 字符
✅ 续行正确缩进

使用方法

功能已自动集成到代码生成器中，无需额外配置。

当运行代码生成命令时，所有超长的参数注释都会自动换行:

dart run swagger_generator_flutter generate --all

注意事项

换行只针对参数文档（- paramName: description 格式）
其他类型的文档注释使用通用的 _wrapDocLine 方法
续行使用两个空格缩进，保持视觉上的层次关系
断点选择优先考虑标点符号，保持语义完整性

5.5 KiB Raw Blame History Unescape Escape