[2.0] Include `w` field of `p5.Vector` in documentation
Nobody has claimed this yet.
- 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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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