misc on inline ref guide, style guide, how ref gen works, add two json examples (folder)

add note about PR 1121 - "broken p5.* links"
question on jsdoc best practices doc

started a section on how reference-generation works
this likely should go in a separate document
add example json from reference generation (+new folder)

doc style guide: update and link to inline reference guide
correct the final "Assets" section

clarify that @module and @submodule are for documentation purposes
mention @submodule and @for missing from jsdoc

Author: nbogie

contributor_docs/contributing_to_the_p5js_reference.md

@@ -10,9 +10,9 @@ In p5.js, we author the code reference you see on the [reference](https://p5js.o
 
 This document will show you how to write and format the reference comments so that they can eventually be rendered onto the website correctly. You should follow this guide whenever you are editing or writing a reference for any p5.js function or variable.
 
-### Aside: A note about versions
+### A note about versions
 
-This document primarily describes p5 version 2.x, whose reference documentation is currently being hosted at https://beta.p5js.org/reference/. Important differences between how p5 v1.x and v2.x are documented will be mentioned in order to help the reader who encounters examples of both formats - or tooling - in the wild.
+This document describes p5.js version 2.x, whose reference documentation is currently being hosted at https://beta.p5js.org/reference/.  Important differences between how p5 v1.x and v2.x are documented will be mentioned in order to help the reader who encounters examples of both formats - or tooling - in the wild.
 
 ## A quick introduction to how reference comments work
 
@@ -112,7 +112,7 @@ Note that block comments starting with `/*` rather than `/**` will be _ignored_
 
 ### Differences between p5 v1 and v2
 
-Note that p5 v1.x does _not_ use JSDoc syntax but a slightly  modified [syntax called YUIDoc](https://yui.github.io/yuidoc/syntax/index.html).  In practice the syntaxes are largely compatible but there _are_ differences.
+Note that p5 v1.x does _not_ use JSDoc syntax but a slightly  modified [syntax called YUIDoc](https://yui.github.io/yuidoc/syntax/index.html).  In practice the syntaxes are largely compatible but there are some differences.  This document will highlight any important ones.  See also the list in [this appendix](#appendix-syntax-differences-between-yuidoc-and-jsdoc").
 
 Syntax and tooling per version
 
@@ -692,12 +692,39 @@ p5.prototype._start = function () {
 
 ### `@module` and related tags
 
-At the top of each source code file will be a `@module` tag. Modules correspond to a group of features in p5.js which on the rendered reference page on the website are split into the corresponding sections. Inside each module, there are additional submodules defined with the `@submodule` tag.
+#### @module and @submodule
+
+At the top of each source code file will be a comment block with a `@module` tag. A module is a top-level grouping of features in the reference pages on the website.  This does _not_ necessarily correspond to any specific software `module` concept in the code iteself.
+
+After the `@module` tag, an optional `@submodule` tag can be used to further group features for the website.  This `@submodule` tag can be set differently on any comment block in the file to change the submodule for a specific feature.
+
+The convention p5.js follows is that each subfolder in the `src/` folder will be one `@module` while each file inside the subfolder will be its own `@submodule` under the overall subfolder’s `@module`. Unless you are adding new subfolders/files to the p5.js source code, you shouldn’t need to edit a file's top-level reference comment block.
+
+On the website, the [top-level reference page](https://beta.p5js.org/reference) presents a list functions and variables grouped by their modules and submodules.
+
+Examples:
+
+The ["Image" module](https://beta.p5js.org/reference/#Image) in `src/image` has the following submodules: "Loading & Displaying", "Pixels", and "p5.Image".
+
+The ["Color" module](https://beta.p5js.org/reference/#Color) in `src/color` has the following submodules: 
+ "Creating & Reading", "Setting", and "Color Conversion".
+
+The _conceptual_ ["3D" module](https://beta.p5js.org/reference/#3D) documents code  mostly from `src/webgl` (there is no `src/3D`), and has the following submodules: "Camera", "Interaction", "Lights", "Material", "strands", "p5.Camera", "p5.Shader".
+
+#### The @for tag
 
 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? -->
+
+#### The @requires tag
+
 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? -->
+
+Example of `@for` and `@requires`
+
 ```js
 /**
  * @module Color
@@ -708,8 +735,6 @@ The `@requires` tag defines the required imported modules that the current modul
  */
 ```
 
-The convention p5.js follows is that each subfolder in the `src/` folder will be one `@module` while each file inside the subfolder will be its own `@submodule` under the overall subfolder’s `@module`. Unless you are adding new subfolders/files to the p5.js source code, you shouldn’t need to edit this reference comments block.
-
 
 ### `@class` tag
 
@@ -813,6 +838,10 @@ npm run custom:cleanup
 
 * YUIDoc requires function names be provided with the `@method` tag, whereas JSDoc can generally extract that information from the implementation source code.
 
+* JSDoc does not have either `@submodule` or `@for` tags (YUIDoc does) but we continue to use them throughout the v2.x codebase as a mechanism by which we group functions, variables, and classes on the website. If you run `documentation lint` you'll see complaints about these tag but Documentation.js collects the tagged information into its output without problem.
+
+* YUIDoc code examples (tagged with @example) are automatically wrapped with `<span>` and other markup.  For documentation.js, we write the wrapping `<div>` and `<code>` elements around the example code ourselves.
+
 ## Appendix: Summary of other documentation differences between p5 v1 and v2
 
 For the syntactic differences between YUIDoc and JSDoc, see above.  Here are some other differences:
@@ -827,15 +856,16 @@ For the syntactic differences between YUIDoc and JSDoc, see above.  Here are som
 
 ## Appendix: About the reference-generation process
 
-In the p5.js repo, `npm run docs` runs (roughly):
-```bash
-"documentation build ./src/**/*.js  
-  -o ./docs/data.json 
-  && node ./utils/convert.mjs",
-```
-### Flow diagram for reference generation
+<!-- TODO: move this out to a separate linked file -->
+
+You don't need to know _any_ of the following to successfully write and maintain the reference comments in the p5.js library!
+
+Here's how things work in Feb 2026 - be wary, this description may well be out of date!
+
+//TODO: attach a label/caption.  The following prose is essentially the correct screenreader text.
+
+#### Flow diagram for reference generation
 
-See [mermaid flowchart syntax reference](https://mermaid.ai/open-source/syntax/flowchart.html)
 
 ```mermaid
 graph LR
@@ -857,10 +887,115 @@ graph LR
   end
   
 ```
-### Flow diagram for search index generation
+
+#### reference generation explained
+
+Either a human or Google Actions (CI) executes this command from the p5.js repo:
+```bash
+npm run docs
+```
+You can run it locally and observe the outputs.
+
+* TODO: what should be true once this command finishes?
+* TODO: when does this command get run?
+
+In turn this command runs:
+
+```bash
+"documentation build ./src/**/*.js  
+  -o ./docs/data.json 
+  && node ./utils/convert.mjs",
+```
+
+This is actually two commands, first `documentation build ...`, and then - if the first command was successful `node ./utils/convert.mjs`.  We'll look at these in turn.
+
+#### The `documentation build...` command
+
+In summary this command turns JSDoc comment blocks across all the javascript files into a single structured json file ready for further processing.
+
+In more detail:
+
+`documentation build` is the [standard way](https://github.com/documentationjs/documentation?tab=readme-ov-file) to invoke documentation.js to build docs.
+
+* The `-o` is used to specify the output file.
+* `documentation.js`'s default output format is JSON, so JSON content is written into the output file.
+
+It's important to note this output does not generate HTML pages, even though that's a common use for tools like documentation.js.
+
+You can run this command yourself locally and inspect the output file to see the gathered data.
+
+You can also run `npx documentation build --help` to read the manual page for documentation.js.
+
+#### The `node ./utils/convert.mjs` command
+
+The second command is
+```bash
+node ./utils/convert.mjs
+```
+
+This will _only_ run if the documentation build command runs successfully.
+
+The `./utils/convert.mjs` script reads the output file generated by the `documentation build` command (the JSON file `/docs/data.json`), and creates three new output files: 
+* `/docs/reference/data.json` - Used by the p5.js-website to generate the reference pages
+* `/docs/reference/data.min.json` - A smaller version of the above
+* `/docs/parameterData.json`
+
+The file generated initially by `documentation build` is _very_ large with a lot of data our pages won't need.  Further, pieces of information are also scattered over the file -  we'd like to group them together into a structure that will make it easier to use in later webpage generation.
+The convert script has taken only what's necessary and grouped it together into the new data file `/docs/reference/data.json` and its minified version.
+
+This file will be used by the p5.js-website to generate the final pages, and by another build process on p5.js repo to build the types.
+
+TODO: link to type-generation process description elsewhere.
+
+It has also generated /docs/parameterData.json` which is used by the friendly error system (FES) at runtime to validate function parameters.
+
+#### Excerpt of /docs/reference.data.json
+
+Here's an excerpt from `/docs/reference/data.json`, showing how our `sin` function documentation is now represented at the end of `npm run docs`
+
+```json
+{
+  "name": "sin",
+  "file": "src/math/trigonometry.js",
+  "line": 526,
+  "itemtype": "method",
+  "description": "<p>Calculates the sine of an angle.</p>\n<p><code>sin()</code> is useful for many geometric tasks in creative coding. The values\nreturned oscillate between -1 and 1 as the input angle increases. <code>sin()</code>\ncalculates the sine of an angle, using radians by default, or according to\nif <a href=\"#/p5/angleMode\">angleMode()</a> setting (RADIANS or DEGREES).</p>\n",
+  "example": [
+    "<div>\n<code>\nfunction setup() {\n  createCanvas(100, 100);\n\n  describe('A white ball on a string oscillates up and down.');\n}\n\nfunction draw() {\n  background(200);\n\n  // Calculate the coordinates.\n  let x = 50;\n  let y = 30 * sin(frameCount * 0.05) + 50;\n\n  // Draw the oscillator.\n  line(50, y, x, y);\n  circle(x, y, 20);\n}\n</code>\n</div>\n\n<div>\n<code>\nfunction setup() {\n  createCanvas(100, 100);\n\n  background(200);\n\n  describe('A series of black dots form a wave pattern.');\n}\n\nfunction draw() {\n  // Calculate the coordinates.\n  let x = frameCount;\n  let y = 30 * sin(x * 0.1) + 50;\n\n  // Draw the point.\n  point(x, y);\n}\n</code>\n</div>\n\n<div>\n<code>\nfunction setup() {\n  createCanvas(100, 100);\n\n  background(200);\n\n  describe('A series of black dots form an infinity symbol.');\n}\n\nfunction draw() {\n  // Calculate the coordinates.\n  let x = 30 * cos(frameCount * 0.1) + 50;\n  let y = 10 * sin(frameCount * 0.2) + 50;\n\n  // Draw the point.\n  point(x, y);\n}\n</code>\n</div>"
+  ],
+  "overloads": [
+    {
+      "params": [
+        {
+          "name": "angle",
+          "description": "the angle, in radians by default, or according to if <a href=\"/reference/p5/angleMode/\">angleMode()</a> setting (RADIANS or DEGREES).",
+          "type": "Number"
+        }
+      ],
+      "return": {
+        "description": "sine of the angle.",
+        "type": "Number"
+      }
+    }
+  ],
+  "return": {
+    "description": "sine of the angle.",
+    "type": "Number"
+  },
+  "class": "p5",
+  "static": false,
+  "module": "Math",
+  "submodule": "Trigonometry"
+},
+```
+
+## Appendix: Flow diagram for search index generation
 
 On the p5js-website repo, we run `npm run build:search`
 
+
+See [mermaid flowchart syntax reference](https://mermaid.ai/open-source/syntax/flowchart.html)
+
 ```mermaid
 graph LR
   contentReference["/content/reference"]@{shape: docs}
@@ -873,8 +1008,8 @@ graph LR
   contentExamples --> genSearchIndexForExamples
   buildSearchIndices --> saveSearchIndex[[saveSearchIndex]] --> outDir[[public/search-indices en.json, ja.json, ...]]@{shape: docs}
 ```
-### Type-generation
-
+## Appendix: Type-generation
+<!-- TODO - in a separate document -->
 On the p5js repo...
 
 `npm run generate-types` runs:
@@ -885,6 +1020,8 @@ On the p5js repo...
 
 ## TODO:
 * move this TODO section out before submitting PR
+* overhaul the style guide.  shared material?
+* where should assets instructions live (where to put store assets and how to refer to them)?  in the [documentation style guide](./documentation_style_guide.md) or here?
 * Finish and place the flow diagrams for doc-gen.  ?where?
 * Replace first example in Adding examples - it doesn't run no setup or draw.  allowed but v unusual in the repo.
 * perhaps acknowledge that there are limits to the types info we can carry in JSDoc and that types are currently sometimes patched in patch.mjs.
@@ -895,19 +1032,35 @@ On the p5js repo...
 * check if tagging incomplete snippets in the markdown as js is harmless (e.g. doesn't break the highlighter library).  It provides useful best-effort syntax-highlighting in some contexts, helping to spot errors.
 * ? run a comprehensive broken-link check? broken example check?  develop one?
 * add a ToC?  there's one on the side panel but it doesn't give a good overview.
+* document the @beta tag (used in e.g. p5.strands)
 
 ## TODO: Questions to ask
+* Opinions on keeping [JSDoc best practices](https://beta.p5js.org/contribute/jsdoc/)  separate?  merging it?
+
+* Check what this is doing at the top of image.js:
+```
+ * @module Image
+ * @submodule Image
+```
+  * is it attempting to create a submodule to be presented as a sibling of the other submodules?
+  * saying the features should be categorised without a distinct submodule? (for that, it's possible to omit the submodule tag)
+
+
 * What's the url-forming rule for in-documentation linking?
 ```
 `#/p5/circle` goes to `p5/circle` but 
 `#/p5.Vector` goes to `p5/p5.Vector`
 ???           goes to `p5.Vector/setMag`
 ???           goes to `p5.Vector/fromAngle`
 
+Also see ["#1121 Fix broken p5.* reference links in reference pages"](https://github.com/processing/p5.js-website/pull/1121).
+ 
 ```
 * The existing guide shows how to write examples with no setup or draw fn, which are auto-wrapped in setup. Codebase doesn't use this.  Downplay / remove the mention of this mechanism?
 * Accept this? "Generally, each example should be a self-contained complete sketch that will run on the reference website and which could be run directly if pasted into the web editor (for example)."  
-* Accept the following?: Multiple examples are not always separated by @example in the repo.  JSDoc says they should be, so i've said that.  The guide previously said just put a blank line and then new codeblock.
+* Accept the following?: Multiple examples are not always separated by @example in the repo.  JSDoc says they should be, so i've said that.  The guide previously said just put a blank line and then new codeblock.  Examples where used: ellipse in src/shape/2d_primitives.js
+  * regex to find interleave @example tag use `+\* *<\/div>\n *\* *\n *\* *@example`
+
 * assets: 
   * ? say anything about licensing (e.g. for assets)
   * ? say anything about preferred file formats (for size, for browser compat, for licensing?)
@@ -923,3 +1076,8 @@ On the p5js repo...
 
 ## Resolved questions
 * Whether to recommend omitting @method tag or not? I'm assuming no: its presence reduces ambiguity and helps codebase search.
+* Confirm that @module and @submodule are constructs for documentation organisation, and don't necessarily indicate the existence of actual software modules of the same name. (I'm happy that's so)
+
+### Author appendix: useful tools
+
+* grep for modules that don't have submodules: `@module \w+\n +\* +@[^s]`

contributor_docs/documentation_style_guide.md

@@ -15,7 +15,7 @@ Our community is large and diverse. Many people learn to code using p5.js, and a
 ## Table of Contents
 
 ### Writing
-- [documentation.js and JSDoc](#documentation.js-and-jsdoc)
+- [documentation.js and JSDoc](#documentationjs-and-jsdoc)
 - [English](#english)
 - [Oxford Comma](#oxford-comma)
 - [Wording](#wording)
@@ -44,11 +44,11 @@ Our community is large and diverse. Many people learn to code using p5.js, and a
 
 ## documentation.js and JSDoc
 
-We use [documentation.js](https://documentation.js.org/) to generate the p5.js API documentation.
+We use [documentation.js](https://documentation.js.org/) to generate the p5.js API documentation from [JSDoc](https://jsdoc.app/) comments in the p5.js source code.
 
-TODO: add or link to instructions for generating and previewing the reference docs.
+Refer to the [inline documentation guide](./contributing_to_the_p5js_reference.md) for more information on how to structure the documentation comments and what tags to use.
 
-Refer to the [inline documentation guide](./contributing_to_the_p5js_reference.md) for more information.
+It also discusses how to generate and preview the reference documentation to see your changes.
 
 **[⬆ back to top](#table-of-contents)**
 
@@ -1265,25 +1265,30 @@ class Mover {
 
 ## Assets
 
-- Always load assets from a folder called "assets".
+Whether assets (such as images, fonts, sound files, etc) are being used in the descriptions or code examples of the reference documentation, or in tutorials, the same rules apply:
 
-> Why? It models good project organization. It's also required for assets to load on the p5.js website. Place assets in the following folders to include them in our online documentation:
-- Examples: [src/data/examples/assets](https://github.com/processing/p5.js-website/tree/main/src/data/examples)
-- Reference Pages: [src/templates/pages/reference/assets](https://github.com/processing/p5.js-website/tree/main/src/templates/pages/reference/assets)
-- Learn Pages: [src/assets/learn](https://github.com/processing/p5.js-website/tree/main/src/assets/learn)
+- Always load assets from a folder called `assets`.
+- Store the assets in the `public/assets` folder of the p5.js-website repository.
+
+> Why? It models good project organization. It's also required for assets to load on the p5.js website. 
 
 ```javascript
 let img;
 
 // Bad.
-function preload() {
-  img = loadImage('moonwalk.jpg');
+async function setup() {
+  img = await loadImage('moonwalk.jpg');
+  //...
 }
 
 // Good.
-function preload() {
-  img = loadImage('assets/moonwalk.jpg');
+async function setup() {
+  img = await loadImage('assets/moonwalk.jpg');
+  //...
 }
 ```
 
+There is more on working with assets in the guide: [Contributing to the p5.js reference](./contributing_to_the_p5js_reference#assets-in-examples).
+
+
 **[⬆ back to top](#table-of-contents)**