如何仅保留特殊标记内容生成外部文档？无需批量标记@internal

核心方案：反向标记+条件文档实现 #

完全不用给所有内部内容加@internal标记，采用反向逻辑只标记需要对外暴露的内容，再结合条件文档过滤输出即可，具体实现方式如下：

1. 用@external标记需公开的内容 #

在需要对外展示的页面、函数、类上添加自定义的@external标记（比如你示例里的页面「Public documentation」和函数func()），其余未标记内容默认视为内部内容。

2. 通过条件文档筛选输出 #

主流文档生成工具（如JSDoc、Doxygen）都支持条件筛选逻辑，以JSDoc为例，可按以下步骤操作：

• 在配置文件中声明@external为可识别的自定义标签
• 利用工具的过滤规则，只保留带有@external标记的内容：

  /**
   * @external
   * @page public_docs Public documentation
   * 对外公开的页面内容
   */
  
  /**
   * @external
   * @func func
   * 对外公开的函数
   */
  function func() { /* ... */ }
  
  /**
   * 内部函数，不会出现在外部文档中
   */
  function internalFunc() { /* ... */ }
  

• 在文档生成命令或配置里添加规则，仅提取带@external标记的元素，忽略未标记内容。

3. 替代方案：配置文件规则过滤 #

如果工具支持，也可直接在配置文件中设置规则：指定仅包含带有@external标签的节点，排除所有未匹配该标签的内容，无需逐个标记内部元素。

文件路径筛选的补充建议 #

如果按文件名/路径筛选困难，优先用标签标记的方式更灵活——毕竟文件划分不一定完全对应内外内容，而标签可以精准定位到单个页面、函数或类，更适配你的场景。

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