p5.js
p5.js copied to clipboard
processing
p5.Vector explanation of setMag
Actual Behaviour
in https://p5js.org/reference/#/p5.Vector
Set the magnitude of this vector to the value used for the len parameter.
Expected Behaviour
if I understand correctly
Set the magnitude of this vector to the value used for the mag parameter.
That is set to match the parameter name in https://p5js.org/reference/#/p5.Vector/setMag. Changing it to be mag in both places is fine but I wonder if it would cause confusion with the mag() method in some way (maybe that's why it is named len in the first place).
Thanks, now I see... I thought it's about mag() but in fact in the url you pointed it has len as a parameter of setMag(len). I feel it's a bit confusing in the p5.Vector page because len does not appear there. I don't know what would be a better description though :(
It seems the two descriptions have to match because of how the p5.Vector class is rendered, they are fetched from the same string.
that's what I thought after your first comment. The more I read the sentence I feel it sounds strange. What about
Set the magnitude of this vector to len (the first parameter)
is that still too wordy? do we need feedback from other people to change it?
It still feels a bit off to me.
For a bit of context, the existing description is taken from Processing word for word while the setMag() in Processing's PVector class has a different description. I'm not sure about how difficult it is to seperate the two on p5.js and I'm a bit reluctant to do it now as I'm exploring refinements to the whole render proceess.
Some additional feedback would definitely be helpful.
I think this could be simplified to just say "Set the magnitude of the vector." Maybe this is less confusing? My assumption would be that if someone is using setMag() they have wrapped their head around parameters a bit already, and would be able to follow the format of the documentation to use the method. But I think your proposed update to the language makes sense as well.
I think that corrently is very clear. Magnitudes is size of the vector. Len is size from one point to another.
Thank you all for working on this issue. I am inviting the current Math stewards to this discussion @limzykenneth, @ericnlchen, @ChihYungChang, @bsubbaraman, @albertomancia, @JazerUCSB, @tedkmburu, @perminder-17, @Obi-Engine10, @jeanetteandrews. Would love to hear what y'all think. Thanks!
I think the documentation wording has been changed since the original issue, in August 2023 (commit details).
The setMag() description reads:
Sets a vector's magnitude to a given value.
And the p5.Vector description introduces both the terms 'magnitude' and 'length':
Vectors have both magnitude (length) and direction.
I personally think this works, and agree with @limzykenneth's earlier point that changing the parameter name from len to mag might cause confusion with the mag() method; introducing magnitude and length as interchangeable terms seems like a good way to go about it. There is now a small typo, with (Optional) being written twice.
Do others think that the current explanations are clear enough?
