processing / processing/p5.js

[2.0] Include `w` field of `p5.Vector` in documentation

Open
#8,154 8 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

Area:Math Bug Good First Issue p5.js 2.0+
Dominant language
JavaScript
Stars
24k
Forks
3.8k
Avg merge
3d 16h
Merged PRs (30d)
25

Description

[2.0] Stabilize w field of p5.Vector

A task list is below.

1. Decide whether to release (consider confusion and utility):

There are a couple of considerations.

Potential confusion:
Most users, especially beginners, will be unfamiliar with homogeneous coordinates, and will therefore be unfamiliar with the usual $(x, y, z, w)$ naming convention. They may guess that the order of coordinates is alphabetical, and this impression would be reinforced by the alphabetical ordering of the reference entries.

This confusion could be mitigated by clear documentation on the x, y, z, and w reference pages. These would need to be clearer than they currently are (right now, the full documentation is simply "The x component of the vector" for x, and is similar for the other components). However, it may not be necessary to release w into the public API (see the next section).

Limited utility?
A proposed Transform class would abstract away the need for homogeneous coordinates, with methods like applyToPoint() and applyToDirection(). These use homogeneous coordinates internally to distinguish points (which can be translated) from directions (which cannot be translated), so the user doesn't ever need to touch a w coordinate. If we think they won't need to use w coordinates, then it may not be worth it to release them into the public API. On the other hand, if we can find practical, concrete use cases that wouldn't already be handled by Transform, then it may make sense to release w to users, since the confusion it might cause may not be especially great.

2. Fix documentation

If we decide not to release w:
We could add a @private tag to its docs.

If we decide to release w:
Currently, a documentation error prevents this feature from appearing in the beta docs. Properties declared with get and set are typically documented by documenting the getter only, using the @type tag, instead of @returns, which is currently used. Once the getter documentation is fixed, the setter documentation may be deleted. At least, I think this should work.

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

Start with the p5.Vector getter and setter documentation in src/math/p5.Vector.js, especially the getter documentation referenced around line 190. First resolve whether w should be public using the confusion and utility considerations in the issue. Done means the chosen API status is reflected in the docs and the beta documentation generation no longer omits or mishandles w.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript
Domain
documentation
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.