draft: updating contributing_to_the_p5js_reference for v2 by nbogie · Pull Request #8462 · processing/p5.js

nbogie · 2026-01-28T04:00:36Z

Addresses #8454
WIP. This PR is meant only as an early draft for discussion, just now.

Changes in summary:

update inline reference guide - contributor_docs/contributing_to_the_p5js_reference.md

for v2.0 correctness
cover some missing basics
add lots more examples
re-write and reformat some content for readability

update style guide for v2.0 correctness - /contributor_docs/documentation_style_guide.md

changes in more detail

regarding main document: /contributor_docs/contributing_to_the_p5js_reference,

comprehensive overhaul for v2.0 correctness, detail, and (hopefully) readability, as follows:
update first sections
- improve first para
- add an abstracted overview of a comment block
update description section
- add importance of first sentence of desc, inc many examples
- add how to link to other function/variable docs (TODO: needs clarification)
- examples of markdown, link to markdown syntax guide
update the params section
- add space
- constants different in v2
- added documenting callback fns
- added documenting arrays
- specifying callback functions
- on patching types in emergency (link to reference-generation-process.md)
update return section
- add space
- improve return type discussion
- add examples of returning promise, or array.
on code examples:
- wrote on complexity of examples, and self-contained examples
- on providing multiple examples
- add section on modernizr
- mention optional text between examples (needs checked)
on assets:
- document use of assets in description and in code examples
- linked to there from the style-guide's coverage of same
on the sin() example used throughout
- update the sin() doc comment example
- add link to sin() source in repo
on @module and @submodule - clarified this is a documentation concept, gave examples
on how to generate and preview the reference:
- rewrote the section on generating and previewing the reference
- has some repetition now with [/docs/scripts.mjs](mostly pointing at https://github.com/processing/p5.js-website/blob/2.0/docs/scripts.md#testing-the-docs-of-your-fork)
- add section on limitations of the preview website (no search, broken links)
add section on linting doc comments
on the formatting of the document (inline reference):
- add an example max line width for code examples
- avoid wrapping on constant examples
- space out method, param, return (allowing examples for each)
- add more sub-headings and fix level of some headings
- mark all legal jsdoc comment blocks as js for markdown
- reduce width of prose descriptions in example comment blocks for readability, hard-wrapping them to fit. They become very hard to read if they get wrapped.
- break some other long paras for readability.
add various hyperlinks
- link to the relevant official jsdoc tag docs as they come up (@method, @param, @return, etc)
- link to our documentation style guide
- link to our JSDoc best practices doc - needs integration decision
- link to more entries in the reference
- link to p5 source code in some cases
v1-v2 differences
- add an initial aside about p5 versions and this document
- Add section on p5v1 -> p5v2 & yuidoc -> jsdoc
- covered assets, hotlinking, other v1-v2 differences
- also add param constants to v1-v2 differences appendix
- add a non-syntax differences (v1->v2) appendix

regarding document: style guide

* finished, possibly
* Replaced yuidoc mention with documentation.js + jsdoc
* linked to the inline reference guide for generation and preview instructions
* rewrote section on assets (and again link)

regarding document: jsdoc best practices

* not yet touched (doesn't need corrected i think it is a v2 doc)
* TODO: integrate these two?  I think all of the best practice doc content belongs in the main contributing_... guide but for the fact it makes it yet longer.

Screenshots of the change:

TODO

PR Checklist

[ ] checked for bad links
[ ] check build:contributor-docs
[x] spelling check - (american english)
[ ] grammar check

contributor_docs/contributing_to_the_p5js_reference.md

davepagurek · 2026-02-07T21:03:45Z

contributor_docs/contributing_to_the_p5js_reference.md


 The `@for` tag defines the relationship between this module and the overall `p5` class, effectively saying this module is a part of the `p5` class.

+<!-- TODO: clarify the nature of this relationship documented by the @for tag.  Where might this be used - still only in docs?  also in type-gen? elsewhere? -->


Sometimes I think we add it when documentation.js inference fails. The main one I think is in properties of a class that we want to document -- since it doesnt correctly parse when we put the comment block in the class itself, we have to document it outside, and then we need to use @for to attach the docs to the right class.

davepagurek · 2026-02-07T21:04:32Z

contributor_docs/contributing_to_the_p5js_reference.md

 The `@requires` tag defines the required imported modules that the current module depends on.

-```
+<!-- TODO: clarify where this @requires info is made use of.  What responsibilities does the author have to state these correctly and comprehensively? -->


I'm also not sure we really need this, as we use import now rather than assuming other files will be loaded.

davepagurek · 2026-02-07T21:06:21Z

contributor_docs/contributing_to_the_p5js_reference.md

+The website won't be _fully_ functional when partially prepared in this way.  Notably:
+
+* links between pages may be broken
+  * You'll need to manually add a trailing slash '/'


tbh we should probably fix that in the website code when we encounter it and not rely on auto adding of the / on deployments, so we can encourage people to file and fix these if they see them!

(we dont make non-trailing-slash urls work on dev because they dont exist on deploys, and it means relative links work differently than when there's a trailing slash, which means something can work locally but break on the live site.)

Sorry, I'm not clear on this. Do you mean all links in the reference doc comments should be changed to include a trailing slash (in the source code)? Like this:

* <a href="#/p5.Image/">p5.Image</a>

(So far, I think there are zero instances of that in the codebase.)

(low-priority - even if this is so, I'm guessing it doesn't have to make this first v2 overhaul of the guide.)

Update norender to use //META: norender. Remove notest and modernizr completely.

@param

1. clarify @param type recommended but optional 2. add that @return {*} for `any` 3. simplify primitive type capitalization rule.

also, hard wrap applyMatrix example for readability correct anchor syntax

Update inline reference guides for v2

3b8ee24

nbogie force-pushed the fix-contrib-to-ref-guide-for-v2 branch from e679c39 to 3b8ee24 Compare February 6, 2026 19:29

add scrappy notes about build:reference internals

20b830e