p5.js 参考文档贡献指南用 YUIDoc 风格注释驱动官方 Reference 页面的完整实践【免费下载链接】p5.jsp5.js is a client-side JS platform that empowers artists, designers, students, and anyone to learn to code and express themselves creatively on the web. It is based on the core principles of Processing. Looking for p5.js 2.0? http://beta.p5js.org项目地址: https://gitcode.com/GitHub_Trending/p5/p5.js导读本文围绕 p5.js 仓库中面向贡献者的官方文档系统讲解如何编写与格式化 p5.js 的参考注释reference comments——p5.js 官方参考Reference页面上展示的函数说明、签名参数与返回值和使用示例全部由这些与源码共存的注释生成。读完本文你将掌握参考注释块的完整语法method、param、return、property、example、class、module等、多签名与常量参数的规范写法、示例代码与无障碍describe()描述的组织方式以及如何用npm run docs在本地生成并预览参考文档。参考注释reference comments如何工作浏览 p5.js 源码时会看到大量以/**开头、*/结尾、每行以*开头的注释块。它们并非普通注释而是参考文档的“源代码”。以三角函数sin()为例其注释块结构如下/** * Calculates the sine of an angle. sin() is useful for many geometric tasks * in creative coding. The values returned oscillate between -1 and 1 as the * input angle increases. sin() takes into account the current * a href#/p5/angleModeangleMode/a. * * method sin * param {Number} angle the angle. * return {Number} sine of the angle. * * example * div * code * function draw() { * background(200); * * let t frameCount; * let x 50; * let y 30 * sin(t * 0.05) 50; * line(x, 50, x, y); * circle(x, y, 20); * * describe(A white ball on a string oscillates up and down.); * } * /code * /div * * div * code * function draw() { * let x frameCount; * let y 30 * sin(x * 0.1) 50; * point(x, y); * * describe(A series of black dots form a wave pattern.); * } * /code * /div * * div * code * function draw() { * let t frameCount; * let x 30 * cos(t * 0.1) 50; * let y 10 * sin(t * 0.2) 50; * point(x, y); * * describe(A series of black dots form an infinity symbol.); * } * /code * /div */注释块之后通常紧跟定义该函数的真实 JavaScript 代码。p5.js 使用与 JSDoc 语法高度相似的YUIDoc风格注释而非 JSDoc 本身每个注释块会被解析为若干更小的独立元素下文逐一拆解。在 src/math/trigonometry.js 中可以找到该注释对应的真实实现印证“注释 实现”的对应关系fn.sin function (angle) { return Math.sin(this._toRadians(angle)); };从源码看sin()通过this._toRadians(angle)先按当前angleMode()将角度统一转为弧度再交给原生Math.sin计算——这与注释中“根据angleMode设置RADIANS 或 DEGREES解释角度”的描述完全吻合也解释了为何注释中需要以 HTML 链接指向angleMode()的参考页。参考注释块的结构解析把上述sin()注释块拆开可以看到它由以下几个部分构成。函数描述/** * Calculates the sine of an angle. sin() is useful for many geometric tasks * in creative coding. The values returned oscillate between -1 and 1 as the * input angle increases. sin() takes into account the current * a href#/p5/angleModeangleMode/a. */块首是函数的纯文本描述支持 Markdown 语法与 HTML 标签如上面用a交叉引用angleMode参考页。描述应简洁必要时补充函数的行为细节、边界情况与使用注意点尽量把函数“做了什么、怎么用”讲清楚。method、param、return三大标签* method sin * param {Number} angle the angle. * return {Number} sine of the angle.函数注释通常包含上述三个区块每个标签以开头method定义函数名称本例为sin。注意函数名不带括号()。param定义函数接受的参数argument。param后紧跟{}括起的内容是参数类型类型之后的单词本例angle是参数名名字之后的剩余部分是对参数的说明。return定义函数的返回值。return后{}括起的是返回类型类型之后是返回值的说明。参数的标准写法与可选参数参数统一遵循如下格式param {type} name Description here.若参数是可选的optional用方括号把参数名括起来param {type} [name] Description here.例如sin()的参考注释在 src/math/trigonometry.js 中进一步细化了参数语义param {Number} angle the angle, in radians by default, or according to if a href/reference/p5/angleMode/angleMode()/a setting (RADIANS or DEGREES).更深入常数值参数用{Constant}如果参数取值来自 src/core/constants.js 中定义的常量如LEFT、CENTER、RIGHT等则类型必须写为{Constant}并用either关键字列出所有合法取值param {Constant} horizAlign horizontal alignment, either LEFT, CENTER, or RIGHTsrc/core/constants.js集中维护了这些枚举常量参考注释中的取值列表应与该文件中的实际定义保持一致避免文档与实现脱节。返回值的标准写法return {type} Description of the data returned.如果函数没有返回值直接省略return标签即可。更深入链式调用用chainable如果函数返回父对象自身即支持链式调用如fill(...).stroke(...)则可以省略return改用如下标签chainable在仓库中chainable被广泛用于返回p5实例或p5.Element的方法例如 src/shape/attributes.js、src/dom/p5.Element.js、src/webgl/p5.Camera.js 等文件中的大量方法。它向阅读者传达“此方法返回调用者本身可继续链式调用”的语义。附加签名additional signatures多参数重载许多 p5.js 函数支持多种参数组合重载。以background()为例它在参考页的“语法Syntax”部分列出了多套签名对应的注释写法如下/** * method background * param {String} colorstring color string, possible formats include: integer * rgb() or rgba(), percentage rgb() or rgba(), * 3-digit hex, 6-digit hex * param {Number} [a] alpha value */ /** * method background * param {Number} gray specifies a value between white and black * param {Number} [a] */规则要点先从多组参数选项中选择一组按前述格式书写第一个签名的完整注释块第一个注释块结束后继续追加其他签名每个附加签名自成独立的注释块且只使用method与param标签不再重复写描述与return。更深入何时不该拆成多签名如果两个签名之间的唯一差异只是多了一个可选参数则不要拆成独立签名直接在一个签名中把该参数标为可选即可。过度拆分会不必要地增加参考页的复杂度读者需要来回对照多套签名才能理解用法。除非必要尽量少用多签名机制。变量参考p5.js variable reference变量系统变量的参考注释结构与函数类似但使用不同的标签。以mouseX为例/** * The system variable mouseX always contains the current horizontal * position of the mouse, relative to (0, 0) of the canvas. The value at * the top-left corner is (0, 0) for 2-D and (-width/2, -height/2) for WebGL. * If touch is used instead of mouse input, mouseX will hold the x value * of the most recent touch point. * * property {Number} mouseX * readOnly * * example * div * code * // Move the mouse across the canvas * function draw() { * background(244, 248, 252); * line(mouseX, 0, mouseX, 100); * describe(horizontal black line moves left and right with mouse x-position); * } * /code * /div */变量注释的关键区别用property代替method来定义变量名。property的书写方式与param相同{类型}在前随后是属性名readOnly标签大多数 p5.js 系统变量都带此标签表明该值由库内部维护不应被用户覆盖。在 src/events/pointer.js 中可以找到mouseX属性的参考注释其后的实现负责在鼠标/触摸事件中更新该值与注释中“触摸输入时保存最近触点 x 值”的描述相互印证。添加示例example标签example是注释块中最具实战价值的部分它承载参考页访问者可以直接运行的示例代码。下面的截图展示了red()函数参考页中仅渲染示例代码区域的效果生成该截图的example注释如下* example * div * code * const c color(255, 204, 0); * fill(c); * rect(15, 20, 35, 60); * // Sets redValue to 255. * const redValue red(c); * fill(redValue, 0, 0); * rect(50, 20, 35, 60); * describe( * Two rectangles with black edges. The rectangle on the left is yellow and the one on the right is red. * ); * /code * /div示例的结构规范example标签之后先写 HTMLdiv再写code示例代码写在code与/code之间示例应尽可能简单、小巧有意义、能说明功能、但不过度复杂画布统一为 100×100 像素。如果示例没有显式书写setup()如上例系统会自动为示例包装一个创建 100×100 灰色背景画布的setup()示例的代码风格与更多最佳实践参见 contributor_docs/documentation_style_guide.md。一个功能多个示例可以在一个注释块内放置多个示例第一个div/code块结束后空一行继续写下一组div/code块* example * div * code * arc(50, 50, 80, 80, 0, PI QUARTER_PI, OPEN); * describe(An ellipse created using an arc with its top right open.); * /code * /div * * div * code * arc(50, 50, 80, 80, 0, PI, OPEN); * describe(The bottom half of an ellipse created using arc.); * /code * /divnorender只展示、不运行如果希望参考页只显示代码而不执行给div加上norender类* example * div classnorender * code * arc(50, 50, 80, 80, 0, PI QUARTER_PI, OPEN); * describe(ellipse created using arc with its top right open); * /code * /divnotest跳过自动化测试执行如果示例代码不应在自动化测试流程中执行例如需要用户交互或保存文件的场景给div加上notest类* example * div classnorender notestcode * function setup() { * let c createCanvas(100, 100); * saveCanvas(c, myCanvas, jpg); * } * /code/div两个类可以组合使用如上面同时使用norender notest的保存画布示例。参考测试基础设施test/目录下的视觉与单元测试会自动扫描示例代码因此标记notest能避免交互类示例在无头环境中失败。使用外部资源文件assets如果示例需要加载外部资源图片、字体、JSON 等需要把文件放入 docs/yuidoc-p5-theme/assets 目录可复用该目录已有的文件在示例代码中以assets/filename.ext路径引用。tint()的参考示例即采用此方式加载图片资源。注意docs/yuidoc-p5-theme/assets是docs/目录下唯一允许贡献者新增文件的例外位置其余docs/下的模板文件在大多数情况下不应直接修改。用describe()为每个示例添加画布描述每个新增示例都应调用 p5.js 的describe()函数为画布添加一段可供屏幕阅读器screen reader朗读的文本描述。describe()只接受一个参数简要说明画布中发生了什么事的字符串。一个带描述的双示例写法如下* example * div * code * let xoff 0.0; * function draw() { * background(204); * xoff xoff 0.01; * let n noise(xoff) * width; * line(n, 0, n, height); * describe(A vertical line moves randomly from left to right.); * } * /code * /div * * div * code * let noiseScale 0.02; * function draw() { * background(0); * for (let x 0; x width; x 1) { * let noiseVal noise((mouseX x) * noiseScale, mouseY * noiseScale); * stroke(noiseVal*255); * line(x, mouseY noiseVal * 80, x, height); * } * describe(A horizontal wave pattern moves in the opposite direction of the mouse.); * } * /code * /divdescribe()的实现位于 src/accessibility/describe.js属于 p5.js 无障碍accessibility体系的一部分更完整的无障碍画布描述编写规范可参阅 contributor_docs/web_accessibility.md。进阶标签一private如果某个函数或属性是库内部私有的使用private标签。带private的条目不会渲染到网站参考页其目的是为库自身的内部机制留下文档。典型例子是启动流程方法_start/** * _start calls preload() setup() and draw() * * method _start * private */ p5.prototype._start function () {从当前源码结构看p5 实例的启动逻辑已演进为 src/core/main.js 中的私有方法#_start()内部依次协调preload()、setup()与draw()的生命周期这与注释“_start调用preload()setup()和draw()”的描述一致。读者在编写参考注释时凡是仅供内部调用、不应暴露给用户的 API都应打上private。进阶标签二module及其相关标签每个源文件顶部都有一个module标签。模块是对 p5.js 功能的逻辑分组在官网参考页上呈现为一个个章节section模块内部又通过submodule划分出更细的子模块。相关标签的作用如下module定义文件所属的功能模块submodule定义模块内的子模块for定义该模块与p5类之间的关系表明该模块属于p5类的一部分requires定义当前模块依赖、必须被导入的其他模块。一个完整的文件头注释示例/** * module Color * submodule Creating Reading * for p5 * requires core * requires constants */在 src/color/creating_reading.js 中可以找到实际生效的同类注释块。p5.js 的约定是src/下每个子文件夹对应一个module子文件夹内每个文件对应一个submodule。除非在src/中新增子文件夹或文件否则无需编辑这些文件头注释。进阶标签三class与constructor类构造函数使用class与constructor两个标签定义。写法与method类似但类名用class定义constructor标记该类拥有构造函数。以p5.Color为例/** * A class to describe a color. Each p5.Color object stores the color mode * and level maxes that were active during its construction. These values are * used to interpret the arguments passed to the objects constructor. They * also determine output formatting such as when * a href#/p5/saturationsaturation()/a is called. * * Color is stored internally as an array of ideal RGBA values in floating * point form, normalized from 0 to 1. These values are used to calculate the * closest screen colors, which are RGBA levels from 0 to 255. Screen colors * are sent to the renderer. * * When different color representations are calculated, the results are cached * for performance. These values are normalized, floating-point numbers. * * a href#/p5/colorcolor()/a is the recommended way to create an instance * of this class. * * class p5.Color * constructor * param {p5} [pInst] pointer to p5 instance. * * param {Number[]|String} vals an array containing the color values * for red, green, blue and alpha channel * or CSS color. */该示例展示了类注释的完整要素类职责描述可含 HTML 交叉引用、class类名、constructor标记、以及param参数说明支持{Number[]|String}这类联合类型与可选参数[pInst]。p5.Color类的实际实现在 src/color/p5.Color.js。本地生成与预览参考文档p5.js 仓库无需构建或运行官网即可在本地生成并预览参考文档。当前仓库 package.json 中定义了生成命令npm run docs该命令的实际脚本为documentation build ./src/**/*.js ./src/**/**/*.js --shallow -o ./docs/data.json node ./utils/convert.mjs执行后会生成预览所需文件以及核心产物docs/data.json——它正是官网渲染参考页所使用压缩后的同一份数据文件。也就是说本地生成的数据与线上渲染的数据同源贡献者可以放心据此预览效果。docs/下的主要模板文件集中存放多数情况下不应改动唯一例外是向docs/yuidoc-p5-theme/assets添加新资源文件。原文档还提到npm run docs:dev可启动实时预览live preview每当源码注释变更时自动更新参考渲染浏览器需手动刷新页面才能看到变化对在浏览器中预览可运行示例尤其有用。需要说明的是截至当前仓库版本package.json 中并未包含docs:dev脚本读者在使用前应先检查本地仓库的package.json确认可用的命令例如npm run docs与npm run doc。下一步与延伸阅读深入语法JSDoc 与 YUIDoc 的官方文档p5.js 参考注释基于 YUIDoc其语法与 JSDoc 高度兼容编码风格示例代码的编写规范见 contributor_docs/documentation_style_guide.md无障碍规范describe()等画布描述细节见 contributor_docs/web_accessibility.md已知问题参考系统相关的关键 issue 编号为 #6519 与 #6045可在 p5.js 仓库的 issue 列表中检索贡献入门完整的贡献流程参见 contributor_docs/contributor_guidelines.md 与仓库根目录的 CONTRIBUTING.md。掌握上述全部标签与规范后你就能为 p5.js 编写出与官方参考页完全一致的高质量文档——新增函数的说明、多签名、示例与无障碍描述都将通过npm run docs一键生成并供全世界的创作者查阅。【免费下载链接】p5.jsp5.js is a client-side JS platform that empowers artists, designers, students, and anyone to learn to code and express themselves creatively on the web. It is based on the core principles of Processing. Looking for p5.js 2.0? http://beta.p5js.org项目地址: https://gitcode.com/GitHub_Trending/p5/p5.js创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考