在 MongoDB 仓库中为 zstd 自动生成 API 手册gen_html 的注释标记规范与实现原理【免费下载链接】mongoThe MongoDB Database项目地址: https://gitcode.com/GitHub_Trending/mo/mongoMongoDB 仓库通过src/third_party/zstandard引入了 zstd 压缩库的第三方源码其中contrib/gen_html目录下提供了一个名为gen_html的 C 小工具它直接扫描lib/zstd.h头文件按照一套特殊的注释标记约定自动生成一份单页 HTML 格式的 zstd API 手册即仓库中已存在的 zstd_manual.html。读完本文你将掌握这套注释标记规范/*!、/**、/*等的设计逻辑、gen_html的完整使用方式以及从源码层面理解它如何把 C 头文件解析成带目录的 HTML 手册。工具定位为什么要把头文件变成手册zstd 的公开 API 全部集中在单一头文件 zstd.h 中。对使用者而言头文件里的注释就是最权威的文档来源。gen_html的设计思路非常直接不维护单独的文档源文件而是把头文件本身当作文档的单一事实来源——API 签名变了重新生成的手册就会自动跟上不存在文档与代码漂移的问题。该工具位于 gen_html 目录下包含 4 个文件文件作用gen_html.cpp核心解析器单文件 C 程序约 224 行Makefile编译 gen_html 并驱动手册生成自动探测版本号gen-zstd-manual.shShell 版的手册生成入口README.md本工具的原始说明文档注释标记规范手册结构的语法gen_html只识别zstd.h中特定格式的注释块不同起始符对应不同的手册元素。以下是原始 README 定义的完整规范并附上zstd.h中的真实用例注释起始符语义生成效果/*!函数声明注释紧随声明之后先输出函数声明加粗的pre块再输出注释/**与/*-章节注释第一行作为H2标题纳入手册目录/*与/**小节注释第一行作为H3标题并连同展示其后的所有函数声明直到遇到第一个空行/*XX 为其他字符忽略不参与生成zstd.h中大量使用了这套约定。以 Simple API 章节为例zstd.h#L149-L157/*! ZSTD_compress() : * Compresses src content as a single zstd compressed frame into already allocated dst. * NOTE: Providing dstCapacity ZSTD_compressBound(srcSize) guarantees that zstd will have * enough space to successfully compress the data. * return : compressed size written into dst ( dstCapacity), * or an error code if it fails (which can be tested using ZSTD_isError()). */ ZSTDLIB_API size_t ZSTD_compress( void* dst, size_t dstCapacity, const void* src, size_t srcSize, int compressionLevel);这里/*!开头的注释块描述了紧随其后的ZSTD_compress()声明gen_html会将其渲染为加粗声明 说明文字的组合。而形如/* Compression contextzstd.h#L249或/* Decompression contextzstd.h#L276的注释则生成H3小节标题并连同其后的函数声明一起输出。统计当前仓库中的zstd.h共 3020 行/*!函数声明注释有106 处/*小节注释有12 处另有 8 处/**//*!单行声明标记——这些正是手册内容的主要素材。附加规则提高可读性的三项处理原始 README 还定义了以下补充规则它们同样体现在实现中ZSTDLIB_API被移除该宏是 Windows 下导出符号用的修饰符__declspec(dllexport/dllimport)对手册读者无意义渲染时会被剥掉使函数签名更干净typedef自动收录即使 typedef 结构体没有任何注释只要检测到typedef且包含{就会连同其定义体一起收录并以加粗pre块展示/**与/*!单行标记这类注释在声明同行的写法函数声明后紧跟/** ... */会被识别且仅函数声明本身加粗高亮。使用方法编译与生成命令gen_html需要 3 个位置参数gen_html [zstd_version] [input_file] [output_html]zstd_version仅用于手册标题生成 zstd X.Y.Z Manualinput_file头文件路径本仓库中为lib/zstd.houtput_html输出 HTML 文件路径。手动编译并生成的方式与原始 README 一致本仓库实际版本号为 1.5.5cd src/third_party/zstandard/zstd/contrib/gen_html make ./gen_html 1.5.5 ../../lib/zstd.h zstd_manual.htmlMakefile自动化版本号提取与手册刷新实际工作流并不依赖手工填版本号。查看 Makefile 可以看到更完整的自动化设计ZSTDAPI ../../lib/zstd.h ZSTDMANUAL ../../doc/zstd_manual.html LIBVER_MAJOR_SCRIPT:sed -n /define ZSTD_VERSION_MAJOR/s/.*[[:blank:]]\([0-9][0-9]*\).*/\1/p $(ZSTDAPI) LIBVER_MINOR_SCRIPT:sed -n /define ZSTD_VERSION_MINOR/s/.*[[:blank:]]\([0-9][0-9]*\).*/\1/p $(ZSTDAPI) LIBVER_PATCH_SCRIPT:sed -n /define ZSTD_VERSION_RELEASE/s/.*[[:blank:]]\([0-9][0-9]*\).*/\1/p $(ZSTDAPI) LIBVER : $(shell echo $(LIBVER_SCRIPT))要点解读版本号从源码现取用sed从zstd.h中解析 ZSTD_VERSION_MAJOR / MINOR / RELEASE 三个宏当前为 1.5.5拼出完整版本号。这再次印证了头文件即文档源的理念——手册标题、版本号、API 内容三者永远同源两个目标make默认只编译gen_html可执行文件make manual别名all会编译后执行./gen_html $(LIBVER) $(ZSTDAPI) $(ZSTDMANUAL)把输出直接写入doc/zstd_manual.html并打印 Update zstd manual in /doc 提示跨平台处理检测到Windows%操作系统时为可执行文件追加.exe后缀clean目标也相应清理编译选项-O3加上-Wall -Wextra -Wcast-qual -Wcast-align -Wshadow -Wstrict-aliasing1等严格告警。gen-zstd-manual.sh 是同一逻辑的 Shell 版本先用三段sed提取版本号并回显ZSTD_VERSIONx.y.z再调用./gen_html $LIBVER_SCRIPT ../../lib/zstd.h ./zstd_manual.html。二者殊途同归说明手册生成是 zstd 上游的常规发布流程之一。源码剖析gen_html.cpp 的解析流程gen_html.cpp不到 250 行全部逻辑在main()内完成其解析流水线值得逐段对照理解。第一阶段整文件读入内存while (getline(istream, line)) { input.push_back(line); }参数校验后不足 3 个参数即打印 usage 退出见 gen_html.cpp#L91-L94逐行读入头文件存入vectorstring input后续所有解析都基于这个行数组和行号游标linenum进行。第二阶段按行分类处理主循环按优先级依次判断每行属于哪种结构gen_html.cpp#L114-L210typedef 捕获L118-L126行首为typedef且含{时调用get_lines(input, linenum, })一路取到结束大括号整体以preb.../b/pre加粗输出。这解释了 README 中typedef are detected and included even if uncommented的实现单行声明注释L129-L134行内同时出现/**或/*!与*/时直接输出该行内部经print_line处理仅声明部分加粗块注释标记定位L136-L149按/**→/*!→/**→/*-→/*的顺序查找起始标记找到后记录标记后第 3 个字符exclam!、*、-或作为分支依据找不到任何标记则continue跳过该行。注意查找顺序是有意为之/**必须先于/**匹配否则会误判。第三阶段注释块提取与清洗定位到标记后get_lines(input, linenum, */)收集到块结束符为止的所有行L151-L160然后做四步清洗首行截掉标记前缀line.substr(spos3)末行截掉*/及其后内容去掉每行行首的*或*续行缩进用trim(comments[l], *-)剥掉行首尾的*、-、字符——这正是 README 中提到的标题前后装饰线如/* Streaming compression functions */在输出中消失的原因移除首尾的空行。第四阶段按标记类型渲染 HTML清洗后的注释进入三路分支exclam !/*!函数声明L162-L181先erase(comments.begin())删掉注释首行形如ZSTD_XXX() :的函数名提示行因为签名本身马上就会展示然后从下一行开始用get_lines(input, linenum, )以空行为终止符抓取函数声明体——这就是switch comments with declarations注释与声明位置互换的实现输出时声明在前、说明在后。声明中前导的ZSTDLIB_API或等宽的 12 个空格续行缩进会被剥除exclam /*小节L182-L193首行生成h3其余行作为pre正文随后同样以空行为界抓取后续函数声明并加粗输出与 README show also all functions until first empty line 的约定一一对应其余/**与/*-章节L194-L209首行生成带锚点的h2a nameChapterN/ah2标题/h2同时把标题压入chapters向量用于后续目录章节号自增。行内渲染还有一处细节print_lineL65-L78当一行同时包含代码和/*注释时输出/b注释b把注释部分移出加粗区保证只有纯声明代码是粗体。第五阶段组装最终 HTML所有片段先累积在stringstream sout中因为目录需要先生成、却位于正文之前main()末尾一次性写出L212-L221ostream h1 version /h1\n; ostream hr\na name\Contents\/ah2Contents/h2\nol\n; for (size_t i0; ichapters.size(); i) ostream lia href\#Chapter i1 \ chapters[i].c_str() /a/li\n;最终文档 标题zstd 版本号 Manual 由chapters生成的有序目录#Chapter1、#Chapter2……锚点跳转 全部正文片段。仓库中已提交的 zstd_manual.html 正是这一流程的产物其标题为 zstd 1.5.5 Manual目录包含 Introduction、Version、Simple API、Explicit context、Streaming、Simple dictionary API 等 20 余个章节与zstd.h中的/**章节注释数量完全吻合。小结与适用边界gen_html是一套注释约定驱动的轻量文档生成方案/*!管函数、/**//*-管 H2 章节、/*//**管 H3 小节、其余忽略配合ZSTDLIB_API剥离、typedef自动收录与/**单行标记三项附加规则完整覆盖zstd.h的文档化场景运行前提是已编译好gen_htmlmake且能读到lib/zstd.h版本号参数仅影响标题Makefile 和 gen-zstd-manual.sh 都演示了从版本宏自动提取的完整做法该工具对注释格式有严格假设如/*!声明抓取依赖空行终止、标记查找顺序固定若要将其思路移植到其他头文件的文档生成需要先确认目标头文件的注释风格与这套约定兼容。【免费下载链接】mongoThe MongoDB Database项目地址: https://gitcode.com/GitHub_Trending/mo/mongo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 在 MongoDB 仓库中为 zstd 自动生成 API 手册：gen_html 的注释标记规范与实现原理
在 MongoDB 仓库中为 zstd 自动生成 API 手册gen_html 的注释标记规范与实现原理【免费下载链接】mongoThe MongoDB Database项目地址: https://gitcode.com/GitHub_Trending/mo/mongoMongoDB 仓库通过src/third_party/zstandard引入了 zstd 压缩库的第三方源码其中contrib/gen_html目录下提供了一个名为gen_html的 C 小工具它直接扫描lib/zstd.h头文件按照一套特殊的注释标记约定自动生成一份单页 HTML 格式的 zstd API 手册即仓库中已存在的 zstd_manual.html。读完本文你将掌握这套注释标记规范/*!、/**、/*等的设计逻辑、gen_html的完整使用方式以及从源码层面理解它如何把 C 头文件解析成带目录的 HTML 手册。工具定位为什么要把头文件变成手册zstd 的公开 API 全部集中在单一头文件 zstd.h 中。对使用者而言头文件里的注释就是最权威的文档来源。gen_html的设计思路非常直接不维护单独的文档源文件而是把头文件本身当作文档的单一事实来源——API 签名变了重新生成的手册就会自动跟上不存在文档与代码漂移的问题。该工具位于 gen_html 目录下包含 4 个文件文件作用gen_html.cpp核心解析器单文件 C 程序约 224 行Makefile编译 gen_html 并驱动手册生成自动探测版本号gen-zstd-manual.shShell 版的手册生成入口README.md本工具的原始说明文档注释标记规范手册结构的语法gen_html只识别zstd.h中特定格式的注释块不同起始符对应不同的手册元素。以下是原始 README 定义的完整规范并附上zstd.h中的真实用例注释起始符语义生成效果/*!函数声明注释紧随声明之后先输出函数声明加粗的pre块再输出注释/**与/*-章节注释第一行作为H2标题纳入手册目录/*与/**小节注释第一行作为H3标题并连同展示其后的所有函数声明直到遇到第一个空行/*XX 为其他字符忽略不参与生成zstd.h中大量使用了这套约定。以 Simple API 章节为例zstd.h#L149-L157/*! ZSTD_compress() : * Compresses src content as a single zstd compressed frame into already allocated dst. * NOTE: Providing dstCapacity ZSTD_compressBound(srcSize) guarantees that zstd will have * enough space to successfully compress the data. * return : compressed size written into dst ( dstCapacity), * or an error code if it fails (which can be tested using ZSTD_isError()). */ ZSTDLIB_API size_t ZSTD_compress( void* dst, size_t dstCapacity, const void* src, size_t srcSize, int compressionLevel);这里/*!开头的注释块描述了紧随其后的ZSTD_compress()声明gen_html会将其渲染为加粗声明 说明文字的组合。而形如/* Compression contextzstd.h#L249或/* Decompression contextzstd.h#L276的注释则生成H3小节标题并连同其后的函数声明一起输出。统计当前仓库中的zstd.h共 3020 行/*!函数声明注释有106 处/*小节注释有12 处另有 8 处/**//*!单行声明标记——这些正是手册内容的主要素材。附加规则提高可读性的三项处理原始 README 还定义了以下补充规则它们同样体现在实现中ZSTDLIB_API被移除该宏是 Windows 下导出符号用的修饰符__declspec(dllexport/dllimport)对手册读者无意义渲染时会被剥掉使函数签名更干净typedef自动收录即使 typedef 结构体没有任何注释只要检测到typedef且包含{就会连同其定义体一起收录并以加粗pre块展示/**与/*!单行标记这类注释在声明同行的写法函数声明后紧跟/** ... */会被识别且仅函数声明本身加粗高亮。使用方法编译与生成命令gen_html需要 3 个位置参数gen_html [zstd_version] [input_file] [output_html]zstd_version仅用于手册标题生成 zstd X.Y.Z Manualinput_file头文件路径本仓库中为lib/zstd.houtput_html输出 HTML 文件路径。手动编译并生成的方式与原始 README 一致本仓库实际版本号为 1.5.5cd src/third_party/zstandard/zstd/contrib/gen_html make ./gen_html 1.5.5 ../../lib/zstd.h zstd_manual.htmlMakefile自动化版本号提取与手册刷新实际工作流并不依赖手工填版本号。查看 Makefile 可以看到更完整的自动化设计ZSTDAPI ../../lib/zstd.h ZSTDMANUAL ../../doc/zstd_manual.html LIBVER_MAJOR_SCRIPT:sed -n /define ZSTD_VERSION_MAJOR/s/.*[[:blank:]]\([0-9][0-9]*\).*/\1/p $(ZSTDAPI) LIBVER_MINOR_SCRIPT:sed -n /define ZSTD_VERSION_MINOR/s/.*[[:blank:]]\([0-9][0-9]*\).*/\1/p $(ZSTDAPI) LIBVER_PATCH_SCRIPT:sed -n /define ZSTD_VERSION_RELEASE/s/.*[[:blank:]]\([0-9][0-9]*\).*/\1/p $(ZSTDAPI) LIBVER : $(shell echo $(LIBVER_SCRIPT))要点解读版本号从源码现取用sed从zstd.h中解析 ZSTD_VERSION_MAJOR / MINOR / RELEASE 三个宏当前为 1.5.5拼出完整版本号。这再次印证了头文件即文档源的理念——手册标题、版本号、API 内容三者永远同源两个目标make默认只编译gen_html可执行文件make manual别名all会编译后执行./gen_html $(LIBVER) $(ZSTDAPI) $(ZSTDMANUAL)把输出直接写入doc/zstd_manual.html并打印 Update zstd manual in /doc 提示跨平台处理检测到Windows%操作系统时为可执行文件追加.exe后缀clean目标也相应清理编译选项-O3加上-Wall -Wextra -Wcast-qual -Wcast-align -Wshadow -Wstrict-aliasing1等严格告警。gen-zstd-manual.sh 是同一逻辑的 Shell 版本先用三段sed提取版本号并回显ZSTD_VERSIONx.y.z再调用./gen_html $LIBVER_SCRIPT ../../lib/zstd.h ./zstd_manual.html。二者殊途同归说明手册生成是 zstd 上游的常规发布流程之一。源码剖析gen_html.cpp 的解析流程gen_html.cpp不到 250 行全部逻辑在main()内完成其解析流水线值得逐段对照理解。第一阶段整文件读入内存while (getline(istream, line)) { input.push_back(line); }参数校验后不足 3 个参数即打印 usage 退出见 gen_html.cpp#L91-L94逐行读入头文件存入vectorstring input后续所有解析都基于这个行数组和行号游标linenum进行。第二阶段按行分类处理主循环按优先级依次判断每行属于哪种结构gen_html.cpp#L114-L210typedef 捕获L118-L126行首为typedef且含{时调用get_lines(input, linenum, })一路取到结束大括号整体以preb.../b/pre加粗输出。这解释了 README 中typedef are detected and included even if uncommented的实现单行声明注释L129-L134行内同时出现/**或/*!与*/时直接输出该行内部经print_line处理仅声明部分加粗块注释标记定位L136-L149按/**→/*!→/**→/*-→/*的顺序查找起始标记找到后记录标记后第 3 个字符exclam!、*、-或作为分支依据找不到任何标记则continue跳过该行。注意查找顺序是有意为之/**必须先于/**匹配否则会误判。第三阶段注释块提取与清洗定位到标记后get_lines(input, linenum, */)收集到块结束符为止的所有行L151-L160然后做四步清洗首行截掉标记前缀line.substr(spos3)末行截掉*/及其后内容去掉每行行首的*或*续行缩进用trim(comments[l], *-)剥掉行首尾的*、-、字符——这正是 README 中提到的标题前后装饰线如/* Streaming compression functions */在输出中消失的原因移除首尾的空行。第四阶段按标记类型渲染 HTML清洗后的注释进入三路分支exclam !/*!函数声明L162-L181先erase(comments.begin())删掉注释首行形如ZSTD_XXX() :的函数名提示行因为签名本身马上就会展示然后从下一行开始用get_lines(input, linenum, )以空行为终止符抓取函数声明体——这就是switch comments with declarations注释与声明位置互换的实现输出时声明在前、说明在后。声明中前导的ZSTDLIB_API或等宽的 12 个空格续行缩进会被剥除exclam /*小节L182-L193首行生成h3其余行作为pre正文随后同样以空行为界抓取后续函数声明并加粗输出与 README show also all functions until first empty line 的约定一一对应其余/**与/*-章节L194-L209首行生成带锚点的h2a nameChapterN/ah2标题/h2同时把标题压入chapters向量用于后续目录章节号自增。行内渲染还有一处细节print_lineL65-L78当一行同时包含代码和/*注释时输出/b注释b把注释部分移出加粗区保证只有纯声明代码是粗体。第五阶段组装最终 HTML所有片段先累积在stringstream sout中因为目录需要先生成、却位于正文之前main()末尾一次性写出L212-L221ostream h1 version /h1\n; ostream hr\na name\Contents\/ah2Contents/h2\nol\n; for (size_t i0; ichapters.size(); i) ostream lia href\#Chapter i1 \ chapters[i].c_str() /a/li\n;最终文档 标题zstd 版本号 Manual 由chapters生成的有序目录#Chapter1、#Chapter2……锚点跳转 全部正文片段。仓库中已提交的 zstd_manual.html 正是这一流程的产物其标题为 zstd 1.5.5 Manual目录包含 Introduction、Version、Simple API、Explicit context、Streaming、Simple dictionary API 等 20 余个章节与zstd.h中的/**章节注释数量完全吻合。小结与适用边界gen_html是一套注释约定驱动的轻量文档生成方案/*!管函数、/**//*-管 H2 章节、/*//**管 H3 小节、其余忽略配合ZSTDLIB_API剥离、typedef自动收录与/**单行标记三项附加规则完整覆盖zstd.h的文档化场景运行前提是已编译好gen_htmlmake且能读到lib/zstd.h版本号参数仅影响标题Makefile 和 gen-zstd-manual.sh 都演示了从版本宏自动提取的完整做法该工具对注释格式有严格假设如/*!声明抓取依赖空行终止、标记查找顺序固定若要将其思路移植到其他头文件的文档生成需要先确认目标头文件的注释风格与这套约定兼容。【免费下载链接】mongoThe MongoDB Database项目地址: https://gitcode.com/GitHub_Trending/mo/mongo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考