draft: updating contributing_to_the_p5js_reference for v2 #8462

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

Resolves #8454
WIP.

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
- add a high-level ToC
- 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/class docs
- 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
- mention optional text between examples (needs checked)
- Remove <div><code> wrapper instructions, remove notest, update norender labelling.
on assets:
- document use of assets in description and in code examples
- linked to there from the style-guide's coverage of same
document case: instance and static methods have same name
on @module and @submodule - clarified this is a documentation concept, gave examples
document @beta and @deprecated
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 @class: add dave's section on creating and documenting classes, from his "jsdoc best practices"
on the formatting of the guide itself:
- add an example max line width for code 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.
on the sin() example used throughout
- update the sin() doc comment example
- add link to sin() source in repo
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 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 yuidoc being replaced with documentation.js and yuidoc
- covered assets, hotlinking, other v1-v2 differences
- also add param constants to v1-v2 differences appendix
- add an appendix of differences for documenting v1 and v2

regarding document: style guide

finished, I think
Replaced yuidoc mention with documentation.js + jsdoc
linked to the inline reference guide for generation and preview instructions
rewrote section on assets (and again linked to inline reference guide's coverage of same)
some external links (e.g. to wikipedia) remain broken and can't be fixed here - #878. (I have a fix if wanted)
(links to specific sections of inline reference guide are necessarily fudged to work in prod. foo.md#section becomes foo/#section)

regarding document: jsdoc best practices

incorporated these details into the main guide
jsdoc.md is now empty except for a link to the main guide

PR Checklist

[x] checked for bad links
[x] build:contributor-docs runs
[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

…guide

…n becomes foo/#section breaks them for browsing in source. fixes them for dev and prod.

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