Sway 语言注释完全指南：普通注释、文档注释与 forc doc 自动文档生成-北京尧图网络

Sway 语言注释完全指南普通注释、文档注释与 forc doc 自动文档生成【免费下载链接】sway Empowering everyone to build reliable and efficient smart contracts.项目地址: https://gitcode.com/GitHub_Trending/sw/swaySway 是 Fuel 生态中用于编写智能合约的领域特定语言注释是每个 Sway 源码文件中不可或缺的组成部分。本文以 Sway 参考文档的注释章节为核心系统讲解 Sway 的两类注释——普通注释Regular Comments与文档注释Documentation Comments的语法、使用场景与规范并结合 sway 仓库的解析器实现与 forc doc 工具源码说明文档注释如何被工具链解析并用于自动生成文档。读完本文你将掌握在 Sway 项目中规范书写注释、利用///与//!生成可对外发布的 API 文档的完整能力。注释概览Sway 中的两类注释Sway 语言提供两种用途截然不同的注释对应文档 docs/reference/src/documentation/language/comments/index.md普通注释Regular Comments用于向源码的阅读者传达信息帮助人类理解代码逻辑编译器完全忽略其内容文档注释Documentation Comments用于从外部使用者的角度记录功能与用法是文档生成工具如forc doc提取 API 文档的数据来源。这两种注释在 Sway 中的区分方式与 Rust 高度一致普通注释不会进入任何程序产物而文档注释会被解析器识别为一种特殊的属性attribute进而被文档工具消费。普通注释的两种语法形式普通注释分为两种语法形式// comment行注释/* comment */块注释行注释//第一种形式从两个正斜杠之后开始一直延续到该行末尾。它的特点是单行内注释直到行尾结束跨多行时需要在每一行开头都写上//可以放在代码行的末尾尾随注释。仓库中的配套示例位于 docs/reference/src/code/language/comments/src/lib.sw展示了上述三种用法fn comment() { // imagine that this line is twice as long // and it needed to be split onto multiple lines let baz 8; // Eight is a good number }可以看到两行过长的说明被拆成两段//注释而let baz 8;后面的// Eight is a good number则是典型的尾随注释——它解释了该变量赋值背后的意图。块注释/* */第二种形式同样延续到该行末尾但它真正的价值在于可以跨越多行且不需要每行都书写注释标记。它同样可以作为尾随注释使用。对应的示例位于 lib.swfn block() { /* imagine that this line is twice as long and it needed to be split onto multiple lines */ let baz 8; /* Eight is a good number */ }块注释内可以自由换行格式排版更灵活。根据仓库中的风格指南 style-guide/comments.md//形式在一般情况下更受推荐但在某些需要把注释插入到代码中间的场景下/* */形式则是更合适的选择——例如函数声明的参数列表中可以用块注释标注额外参数的含义因为此时行注释会破坏语句的连续性。普通注释的取舍建议优先使用//行注释语义直观、与 Rust/Solidity 社区习惯一致当注释必须出现在代码行中间如参数列表内部时改用/* */普通注释只服务于人类阅读不会进入编译产物或生成的 ABI也不影响字节码大小。文档注释用///书写可生成文档的 API 说明文档注释以三个正斜杠///开头通常放置在函数上方或结构体等类型的字段上方。它与普通注释最本质的区别在于文档注释会被forc doc等工具读取用于自动生成面向外部使用者的文档。文档注释的典型场景是 structs结构体等类型的字段说明。仓库示例 lib.sw 给出了一个完整的文档注释范本/// Data structure containing metadata about product XYZ struct Product { /// Some information about field 1 field1: u64, /// Some information about field 2 field2: bool, } /// Creates a new instance of a Product /// /// # Arguments /// /// - field1: description of field1 /// - field2: description of field2 /// /// # Returns /// /// A struct containing metadata about a Product fn create_product(field1: u64, field2: bool) - Product { Product { field1, field2 } }这个示例揭示了文档注释的两个要点位置语义///可以放在结构体声明上方、结构体字段上方用///逐个说明每个字段的语义以及函数上方结构化格式函数级文档注释中可以使用#前缀组织段落例如# Arguments列出参数及其说明、# Returns描述返回值这种 Markdown 风格的分节约定可以被文档生成工具渲染为规整的 API 手册。模块级文档注释//!除了///这种“外部文档注释”Sway 还支持//!形式的模块级内部文档注释。根据 forc-plugins/forc-doc/README.md 的说明//!用于在 Sway 文件开头为整个模块/库书写说明例如//! Library containing types used for... library;需要特别注意的是//!内部文档注释只在 Sway 文件的开头有效。如果它出现在文件的其他位置解析器会将其判定为“错位的内部文档注释”misplaced inner doc comment并报错——这一点在 sway-parse/src/attribute.rs 的解析逻辑与单元测试中均有体现。从源码看文档注释的解析链路文档注释并不是被编译器当作普通文本丢弃的——从 sway 仓库的解析器源码可以确认///与//!会被识别为一种特殊形式的属性attribute从而进入类型检查与文档生成的完整链路。词法层DocComment记号在 sway-ast/src/token.rs 中定义了DocComment结构它是词法阶段产生的独立记号类型与普通注释记号分开存储。同时sway-ast/src/attribute.rs 提供了两个构造函数new_outer_doc_comment对应///外部文档注释new_inner_doc_comment对应//!内部文档注释。这证实了文档注释在 AST 层面被统一归入AttributeDecl属性声明并在is_doc_comment()等方法中被标记为文档注释类型。语法层属性解析器sway-parse/src/attribute.rs 的解析流程是解析器在读取一个 item 之前先通过peek_doc_comment检查下一个记号是否为文档注释若是则解析为DocComment并根据doc_styleDocStyle::Outer或DocStyle::Inner分别构造外部或内部文档注释属性压入属性列表。同一文件sway-parse/src/attribute.rs还包含对“错位内部文档注释”的检查当模块末尾只剩下内部文档注释、其后不再有合法 item 时解析器会触发错误提示。该文件的单元测试如//! This is a misplaced inner doc comment.与/// This is an outer doc comment.的组合用例专门验证了这类边界情况。语义层forc doc消费文档注释文档注释的最终消费者是forc doc插件源码位于 forc-plugins/forc-doc。从 forc-plugins/forc-doc/README.md 可以确认其工作流程forc doc首先将 Sway 程序编译为带类型的TyProgram文档分析阶段src/doc/目录遍历程序中的可文档化项声明类 item 与上下文类 item把///注释内容、代码原文等信息收集成Document结构渲染阶段src/render/目录将收集到的信息渲染为 HTML输出到out/doc目录并附带src/static.files/下的 CSS、图标与字体资源完成样式化。也就是说只要在可文档化的 item如abi声明、struct、fn上方书写///注释forc doc就会自动为其生成文档页面。该 README 给出了一个最小示例/// Defines my contract ABI... abi MyContractABI {}命令行使用方式按照 forc-plugins/forc-doc/README.md 的 Quick Start生成与查看文档的操作步骤如下$ cd my_fuel_project $ ls # check Forc.toml exists # src Forc.toml $ forc --version # check forc is installed $ forc doc --version # check forc doc is installed $ forc doc --open # open docs in default browser前提条件已安装forc通过fuelup分发的工具链已内置forc doc也可以使用cargo install --path forc-plugins/forc-doc从源码安装当前目录或父目录包含Forc.tomlSway 代码可以成功编译。开发调试场景下还可以直接运行cargo run -- --path path/to/manifest --open来构建文档并打开浏览器。文档注释编写规范小结综合参考文档、风格指南与 forc doc 的源码实现可以总结出以下实践要点场景推荐写法说明普通单行说明、尾随注释//最常用跨行时每行重复//插入代码中间的多行说明/* ... */不破坏语句结构函数、结构体、字段的 API 说明///可被forc doc提取生成文档模块/库级整体说明//!必须放在 Sway 文件开头参数与返回值说明/// # Arguments//// # Returns结构化分节便于渲染结语注释是 Sway 智能合约代码质量的重要组成部分普通注释//与/* */服务于源码的阅读者帮助你与协作者快速理解逻辑文档注释///与//!则经由解析器识别为属性、最终被forc doc渲染为面向外部使用者的 API 文档。理解这两类注释的语法边界与解析链路既能让你的 Sway 代码更易读也能让合约 ABI 之外的“文档资产”随工具链自动沉淀。完整的语法说明见 docs/reference/src/documentation/language/comments/index.md配套可运行示例见 docs/reference/src/code/language/comments/src/lib.sw风格建议见 style-guide/comments.md文档生成工具的完整使用指南见 forc-plugins/forc-doc/README.md。【免费下载链接】sway Empowering everyone to build reliable and efficient smart contracts.项目地址: https://gitcode.com/GitHub_Trending/sw/sway创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

Sway 语言注释完全指南：普通注释、文档注释与 forc doc 自动文档生成

相关推荐

Zettlr 安装与快速上手：跨平台 Markdown 写作环境 5 分钟搭建

Tabby 的 completion max_input_length 与 max_decoding_tokens 该怎么调？

如何在 RK3566 上跑通 sherpa-onnx 流式语音识别？完整避坑指南

更多资讯

AI全栈开发实战：技术选型、RAG、Agent与生产化全攻略

智能硬件系统开发：数据融合与实时性优化实践

CookLikeHOC 白切鸡（岭南黄熟鸡版）标准化出品指南：白切鸡料配方、分切规格与同底衍生产品解析

Power BI自定义地图开发：高德API与Leaflet.js实战

源代码安全审计收费标准与实施指南

PLC对接扫码支付实战：串口通信与Modbus协议全解析

今日更新

SpacetimeDB C++ 模块库实战：用 C++20 在数据库内构建 WebAssembly 模块

别踩雷！不是所有 AI 写作工具都靠谱，2026 高校认可工具精选

SSM+MySQL幼儿园管理系统源码解析：从部署到优化

本周精选

超人会飞不算本事：系统稳定依赖清晰规则与边界设计

超人VS蜘蛛侠：拆解超级IP的影响力与传播方法论

基于CNN的调制信号识别：MATLAB实现时频图分类实战

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？