a comment added to explain the use of HashMap

[ttulka]

to avoid misconception of contributors about using HashMap to implement a JSON object as a unordered collection by the definition

[stleary]

Since we are going to document this in the code, let's include a thorough explanation, e.g. what design goal is met by using an unordered container and why an ordered container is specifically not used. You can use the text from the Wiki, although I think your own interpretation could be better. This is a good example of how not all code is inherently self-documenting.

[ttulka]

I tried my best. There is actually not a lot of information about this issue and I see several misconceptions in the discussion forums. So, the explanation is very welcome, I guess :-)

[stleary]

What problem does this code solve?
Comment-only change. Since the JSONObject internal container is such a popular object for change, a comment is added to address why it was done this way.

Risks
None

Changes to the API?
No

Will this require a new release?
Can be rolled into the next release

Should the documentation be updated?
No

Does it break the unit tests?
No

Was any code refactored in this commit?
No

Review status
ACCEPTED Starting 3 day timer.