processing / processing/p5.js

[p5.js 2.0 Docs] Change in return value for load functions that use callbacks needs to be documented

Open
#8,280 9 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Discussion
Dominant language
JavaScript
Stars
24k
Forks
3.8k
Avg merge
3d 16h
Merged PRs (30d)
25

Description

Topic

In version 1.x, the load... functions (loadImage, loadJSON, etc.) always returned the loaded data, whether or not callbacks were used. This changed in version 2: now when load.. functions are used with callbacks, they now return the value returned by the callback instead of the loaded item. This is a nice feature that allows a successCallback to dynamically modify the loaded data. It also allows an errorCallback to return some default data. But this feature needs to be described in the documentation for the various load... functions. The need for this was noted by @limzykenneth in a comment on a previous issue, but it looks like it was missed.

This is a breaking change from version 1 to 2 since most version 1 sketches that use both an assignment and a callback function won't return the desired data from the callback function (this has actually broken one of the examples on the p5.js website; see /processing/p5.js-website#1033), so this should be emphasized in the documentation.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Review the documentation entries for the load... functions, starting with loadImage and loadJSON and their existing return-value sections. Document that callback-based calls return the callback's value, including success and error callbacks, and emphasize the v1-to-v2 breaking change. Done when all relevant load-function references consistently describe this behavior.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript
Domain
documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
55/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.