Documentation for +=

[soegaard]

This is a response to:
processing/processing-docs#847

Please reconsider.

The operator += combines assigment and addition.
The documentation explains assignment = as:

Assigns a value to a variable. The "=" sign does not mean "equals", but is used to place data within a variable.

Furthermore, the syntax is listed as:

var = value

From the old issue:

Additionally, the use of more technical language such as "identifiers" and "expressions" may be confusing for beginners, who may not be familiar with these terms. We believe that the current syntax is more straightforward and easier to understand for the intended audience.

The words variablename and expression 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 word expression how about:

var += value

This matches the convention used in the documentation for assignment.

[SableRaf]

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 :)

[Arya-Gupta]

Thanks @SableRaf, I'll get onto this asap.

[Arya-Gupta]

Hey @SableRaf, I've finished working on this issue.

[SableRaf]

Thanks for your contribution! I'll be looking into it right now.

[SableRaf]

@Arya-Gupta, I'm sorry but I am unable to merge your pull request (#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 (processing/processing-doclet#1).

[Arya-Gupta]

@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?

[soegaard]

@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

[Arya-Gupta]

@soegaard I've now spent over an hour searching for it and I don't think its there.
@SableRaf What should I do?

[SableRaf]

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 the processing, sound and video 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.

[runemadsen]

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 script
• originalFile : Set to the full path of the Java file the content came from

This 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.

[SableRaf]

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!

[Arya-Gupta]

Fixed @SableRaf. No problem at all. Please do tag me for any doc-related issues.

[SableRaf]

Merged in a838211 thanks!