p5js Reference should include entries for JavaScript basics

[brysonian]

The reference page on p5js.org seems to assume a basic knowledge of javascript because there aren't pages for things variables and functions. I think it would be hugely helpful to at the very least link to the MDN pages.

I imagine a number of students get lost not knowing where to look when they do get confused about functions, variables, etc.

For context, the processing reference includes pages for int, float, boolean... as well as for, while, etc.

(see also: #3877)

[ProjectGrantwood]

I'm not sure the site needs a whole new set of new reference pages--mostly because there is so much going on in modern javascript, every new reference could be a potential rabbit hole.

However, a one-page reference that differentiates what is the p5js library keywords/syntax from what is pure javascript would be great--with the appropriate links to MDN reference pages, of course. This would be ultra helpful for novice users and probably get to the core of the problem you're expressing.

As a side note, I believe that the original Processing was intended to function more like its own language, not "just a java library"--which is probably why we see int, float, bool, for/while on the Processing reference pages. Somebody correct me if I'm wrong.

[brysonian]

That is true about processing, however pedagogically p5 and processing are taught in very much the same way. Most books and syllabi on learning p5 feature sections on functions and variables and iteration, and most learners are not experienced JS coders (or coders at all!) so the library/language distinction isn't a particularly useful one for their needs. In other words, we don't teach JS, then teach p5, they are taught together at the same time.

It seems like a big ask for a new learner, after just a couple of classes, to be expected to know that when they need help with the syntax of for loop they need to search for "javascript for loop" or look at MDN (that's overwhelming) but when they want to draw an ellipse, they can look at the online reference.

There is no need or use in documenting all of modern javascript but that doesn't mean that there isn't a need to provide help on some fundamentals. I also think we are capable of describing how to use for in much more supportive and helpful terms than MDN.

Also note that many of the functions that reproduce built-in JS functionality like append are deprecated, which I think is great, but will further exacerbate the issue of how to help new learners find what they need.

[stalgiag]

I like this. The additional documentation doesn't have to address all (or even most) of modern javascript but maybe a good rule of thumb could be that any vanilla javascript that is used in the library's reference examples could also have an explainer page in the reference? This could encompass for, if, function, let and a few others without requiring much added work on our side. Language choice for explaining would require some significant initial consideration but maintenance would be more or less non-existent. This could also help with difficult decisions about how much complexity to mask (for an example see the discussion in #3877)

[brysonian]

Working from the examples is perfect. There is also a good list of JS statments on MDN which again i don't think we would need to cover, but gives an idea of what people might encounter / need.

[lmccart]

I like this idea. I think the easiest way to do this with the current reference building setup is to add a file into the src/core folder that contains only commented reference entries, no code.

[outofambit]

i love this idea! as a starting point for discussion i would suggest the following list. (I culled all of them from the JS statements on MDN linke @brysonian shared above.)

• let
• const
• if...else
• function
• return
• class
• do...while
• for
• for...in
• for...of

there's probably some very useful JS utility functions (like parseInt and JSON.stringify) that would be good to add to this list, too (maybe later, though).

[limzykenneth]

Since we are moving towards 1.0, we can maybe also look at removing the deprecated array functions like append and include arr.push() in the documentation instead.

[singhvisha]

hi, I am beginner.
Can I work on this issue?

[stalgiag]

Hello @singhvisha yes definitely! Are you able to generate documentation in your local development setup? If so, try doing what @lmccart suggests and add a file to src/core with only commented reference entries based on the list posted by @outofambit and @limzykenneth. Try to use plain language to describe what the code does and also link to the MDN documentation. If you have trouble at any stage feel free to @ me, and I'll do my best to help. Good luck and thanks for contributing!

[stalgiag]

Also if it becomes overwhelming for whatever reason and you'd like to be unassigned just feel free to @ me or unassign yourself. No pressure!

[shubymao]

Can I also try to work on this or is this a one guy task?

[lmccart]

i think more than one is great! work-in-progress pull requests could be one way to build on each other's work on this

[singhvisha]

hi, whenever I try to commit . It always showing your commit failed with the following error.

vishal@snake:~/p5Original/p5.js$ git commit -m "Added a doc file"
husky > npm run -s precommit (node v10.16.3)

 ↓ Running tasks for ignore [skipped]
   → No staged files match ignore
 ↓ Running tasks for Gruntfile.js [skipped]
   → No staged files match Gruntfile.js
 ↓ Running tasks for grunt-karma.js [skipped]
   → No staged files match grunt-karma.js
 ↓ Running tasks for docs/preprocessor.js [skipped]
   → No staged files match docs/preprocessor.js
 ↓ Running tasks for utils/**/*.js [skipped]
   → No staged files match utils/**/*.js
 ↓ Running tasks for tasks/**/*.js [skipped]
   → No staged files match tasks/**/*.js
 ↓ Running tasks for bench/**/*.js [skipped]
   → No staged files match bench/**/*.js
 ↓ Running tasks for test/**/*.js [skipped]
   → No staged files match test/**/*.js
 ❯ Running tasks for src/**/*.js
   ✔ eslint
   ✖ node ./utils/sample-linter.js
     →     at bootstrapNodeJSCore (internal/bootstrap/node.js:622:3)
✖ node ./utils/sample-linter.js found some errors. Please fix them and try committing again.

/home/vishal/p5Original/p5.js/utils/sample-linter.js:2
import eslint from 'eslint';
       ^^^^^^

SyntaxError: Unexpected identifier
    at Module._compile (internal/modules/cjs/loader.js:723:23)
    at Object.Module._extensions..js (internal/modules/cjs/loader.js:789:10)
    at Module.load (internal/modules/cjs/loader.js:653:32)
    at tryModuleLoad (internal/modules/cjs/loader.js:593:12)
    at Function.Module._load (internal/modules/cjs/loader.js:585:3)
    at Function.Module.runMain (internal/modules/cjs/loader.js:831:12)
    at startup (internal/bootstrap/node.js:283:19)
    at bootstrapNodeJSCore (internal/bootstrap/node.js:622:3)


husky > pre-commit hook failed (add --no-verify to bypass)

[outofambit]

hi @singhvisha we've been seeing that issue intermittently but we haven't gotten a solid fix yet. 😢 (i also need to write up a proposal for modifying that pre-commit hook to be less restrictive.)

in the meantime i would recommend you commit with this command: git commit --no-verify. for your example above it would go like this:

git commit --no-verify -m "Added a doc file"

could you give that a try and let us know how it goes? thank you!! ✨

[singhvisha]

hi, is pull request failed?

[shubymao]

I will start adding to this when the pull request get accepted.

[thumbsupep]

if we're expanding documentation to include things that are not specific to p5.js, does it seem permissible to include examples that dont have any p5.js specific code, but cover old functionality that Processing had? ex processing/p5.js-website#498