R包@format标签添加列表报错，devtools::document()执行失败求助

核心问题定位 #

警告提示的mismatched braces or quotes说明你在@format标签下的文本里，存在未闭合的引号、括号，或者引号/括号配对错误，导致roxygen2无法正确解析文档。

具体排查与修正步骤 #

1. 定位错误行：根据警告里的maturation_cm.R:8，直接打开这个文件的第8行，检查@format相关内容（包括上下相邻行，错误可能跨行存在）。
2. 检查引号配对：
   • 避免在单引号包裹的文本里直接用未转义的单引号，比如错误写法：- col: 'It's a measurement'，内部单引号会和外层单引号冲突。
   • 修正方式：要么换用双引号包裹文本：- col: "It's a measurement"，要么转义内部单引号：- col: 'It\'s a measurement'。
   • 确保所有引号都有对应的闭合符号，不要漏写。
3. 检查括号配对：
   • 检查描述文本里的圆括号、方括号是否都有对应的闭合符号，比如错误写法：- col: (Length in cm，缺少右括号。
   • 嵌套括号也要确保配对，比如(example (text))是正确的，(example (text)则错误。
4. 规范@format的格式：
   数据集的@format标签标准写法参考：

   #' @format A data frame with 3 columns:
   #' - `sample_id`: Unique sample identifier (integer)
   #' - `maturation_stage`: Maturation level (factor with levels: low, medium, high)
   #' - `cm_measurement`: Length in centimeters (numeric)
   

   确保每个列描述项以- 开头，列名用反引号包裹，文本部分语法正确。

验证修正 #

修正后重新运行devtools::document()，如果警告消失，说明问题已解决，man文件夹会生成对应的.Rd文档。

内容的提问来源于stack exchange，提问作者Abdu Kikhia