Closed soegaard closed 1 year ago
Hi @soegaard and thanks for bringing this up again.
This matches the convention used in the documentation for assignment.
Consistency with the assignment reference is a compelling goal.
I propose the following:
Syntax
var += value
Parameters
var
any valid variable name
value
any numerical value of the same type as the variable. For example, if the variable is of type "int", the value must also be an int
Note that this change should be made for all the compound assignment operators included in the documentation: +=
/=
-=
*=
cc @Arya-Gupta if you're still interested to make a PR for this you're welcome to do so :)
Thanks @SableRaf, I'll get onto this asap.
Hey @SableRaf, I've finished working on this issue.
Thanks for your contribution! I'll be looking into it right now.
@Arya-Gupta, I'm sorry but I am unable to merge your pull request (https://github.com/processing/processing-website/pull/417). Changes to the documentation should go in the JavaDoc on the Processing repo (see the README on updating the reference). Apologies for not making that clearer earlier. Would you mind making those changes over there?
Also, just a heads up that we're having a bit of an issue at the moment with the Doclet script that generates the documentation. Changes to the JavaDoc can be merged but they won't show up on the website until we get the script fixed. We're actively working on getting some help to sort it out (if anyone reading this has experience with Doclet scripts, please reply to the issue on the Doclet repo (https://github.com/processing/processing-doclet/issues/1).
@SableRaf According to the readme, I should be making the update somewhere here. However, I'm unable to find the exact file, could you help me out?
@Arya-Gupta FWIW I can't find the relevant source either. The phrase "Combines addition with assignment." is present in the web-site docs, but I can't find any related JavaDoc in the organization.
https://github.com/search?q=org%3Aprocessing+Combines+addition+with+assignment&type=code
@soegaard I've now spent over an hour searching for it and I don't think its there. @SableRaf What should I do?
Hi @Arya-Gupta and thanks for taking so much time researching this. I'm sorry that it wasn't successful, which is entirely due to the rather complicated way the reference is being generated.
I was basing my assessment on this sentence from the README:
You should never edit the
/content/references/translations/en
folder, since it is generated directly from JavaDoc comments in theprocessing
,sound
andvideo
repo.
but I missed the later part that says:
If you are adding content to the reference that does not live in the processing source code (such as some Java functions and
=;<>
symbols), do the following steps.TODO
Well that's awkward 😅 But at least we know the documentation is missing.
We will need some input from @REAS or @runemadsen in that particular case.
Thanks for tagging me in this! I believe that the PR can be merged since all the Java-specific reference content is saved only in the json
files in this repo.
This is how it works: The content/references/translations/en
folder is a mix of json
files that are converted from the processing4
repo (which is most of the files) and some that are authored directly in the folder. This is based on how the old website worked where some xml
files were created from the Processing source code and some xml
files just lived in the website repo.
The rule is that whatever is straight Java should be edited inside this repo and whatever is the Processing API should be edited in the source code. When we fix the Doclet script, I would suggest that we include two new properties in the json
files:
autoGenerated
: Set to true
for files that have been created via the Doclet scriptoriginalFile
: Set to the full path of the Java file the content came fromThis would make it easier to know where to edit the different content items. If we can't find someone to fix the Doclet, we can try giving it a go on our end.
Thanks @runemadsen! I'll update the README to include these clarifications. Regarding the Doclet script, I have called for help on GitHub, Discourse, and Twitter but so far no one has come forward so I would definitely be grateful for you having another look 🙏
@Arya-Gupta: I have reopened your pull request. There is one tiny correction needed which I noted in a comment on the PR. Once this is fixed I will merge your code. Thanks for you patience and your contribution!
Fixed @SableRaf. No problem at all. Please do tag me for any doc-related issues.
Merged in a838211a468e23f30c9f8d9f10ba01ca601aac2a thanks!
This is a response to: https://github.com/processing/processing-docs/issues/847
Please reconsider.
The operator
+=
combines assigment and addition. The documentation explains assignment=
as:Furthermore, the syntax is listed as:
From the old issue:
The words
variablename
andexpression
are well-known from math. As a math teacher of 20 years I can assure you that concepts - not words - confuse beginners.The use of
value += value
is confusing since it conflates the concepts of variable and value. If you are afraid of the wordexpression
how about:This matches the convention used in the documentation for assignment.