[p5.js 2.0 Bug Report]: guide "contributing to the p5js reference" is out of date for v2.x

[nbogie]

Most appropriate sub-area of p5.js?

• Accessibility
• Color
• Core/Environment/Rendering
• Data
• DOM
• Events
• Image
• IO
• Math
• Typography
• Utilities
• WebGL
• Build process
• Unit testing
• Internationalization
• Friendly errors
• Other (specify if possible)

p5.js version

2.2.0

Web browser and version

n/a

Operating system

n/a

Steps to reproduce this

Steps:

1. visit https://beta.p5js.org/contribute/contributing_to_the_p5js_reference/
2. search for JSDoc and YUIDoc. It talks about YUIDoc which is not used in v2.x
3. view these v1.x instructions for typing function params which take constants
4. view section "generating and previewing the reference" which refers to npm scripts non-existent in v2.x

I'd like to work on doing a full update of this document for v2.x

Update: This should include an update of https://beta.p5js.org/contribute/documentation_style_guide/ for 2.0, too.

[ksen0]

Thanks for putting this together! You're welcome to work on this @nbogie, thanks for volunteering.
(cc @davepagurek @perminder-17 for visibility and in case there's open issues that might be related.)

[perminder-17]

Sorry about that, I forgot to update it earlier. This one is still out of date. You can refer to this : https://github.com/processing/p5.js-website/blob/main/docs/scripts.md#testing-the-docs-of-your-fork

we just updated that in the website : processing/p5.js-website#924 but missed in here. Thanks for catching this.

[ksen0]

Hi @nbogie, would it be alright to add https://beta.p5js.org/contribute/documentation_style_guide/ to this? There is a YUIDoc reference here as well. I'm happy to make a separate issue / subissue if you prefer to keep your scope on contributing md. Thanks again for flagging this as a problem area.

[nbogie]

Hi @nbogie, would it be alright to add https://beta.p5js.org/contribute/documentation_style_guide/ to this?

Yes absolutely! Weirdly I just came to github to get this issue number to suggest to dave I roll that change into this!

[nbogie]

There's also this jsdoc best-practices guide (src) (which is in-date for 2.0).

I like how concise it is. Rather than jumping to integrate the two, I'll have a try, first, at linking out from the main guide to the best practices document and we'll see how that feels? Sort of, "You've learned the critical essentials in this guide, but here is a link to our evolving best-practices guide"?

[nbogie]

Question 1: I inferred the following wrt using assets in v2.0 reference examples. Does it sound correct?
Question 2: Are assets in function descriptions also to be hosted in the same place? Looks like it.

---

Including asset files (images, fonts, etc) in examples

If your example code uses external asset files (e.g. images, fonts, sounds), they must be added in the p5.js-website repo's /public/assets folder. Then, link to the asset with assets/filename.ext in the code.

(Note that this is a change from p5 v1.x where such assets were stored in the p5.js repo.)

Examples:

For a full working example, see the tint() reference.

img = await loadImage('assets/rockies.jpg');

The above code will load the image file, /public/assets/rockies.jpg, stored in the p5.js-website repo.

---

You may notice I also now have a draft PR which updates most sections of the document, except the section on generating, previewing the docs, and the section on lesser used JSDoc tags (@module, @Class, etc). I'm not requesting review yet, except for the above section on assets.