Update Documentation

[rasberik]

Pull Request Type

• Bug fix
• New feature
• Refactoring
• Documentation update
• Chore

Description

Update documentation and syntactic & grammar structure of mainly Context and PropertyWrapper parts, and files related to the these changes.

Some examples of repetitive pattern alignments in this PR:

• "noun that to verb" - aligned as "noun to verb"
  • Example: "operator that to reset an asynchronous atom value" → "operator to reset an asynchronous atom value"
• "watch to" phrasal verb seems little off, suggesting to use regular "watch" verb
  • Example: "no longer watched to from anywhere" → "no longer watched from anywhere"
• Preserving original verb form:
  • Example:
    • "to read, write, and otherwise interacting" → "to read, write, and otherwise interact"
    • "Refreshes and then return" → "Refreshes and then returns"
• Method Parameters changes:
  • "The default timeout interval is nil" → "The default timeout interval is nil which indicates no timeout."
  • Missing colon in " - Parameters:"
• "Parameter atom: An atom that associates the value." (repetitive) → find it confusing, since atoms do associate with value, but not always other way around.
  • context specific definition added
• "notifies update to downstream atoms" (repetitive) → removed update or rephrased according to situation
• atoms or/and views - using or & and have subtle difference, so I reviewed all cases and updated respectfully.
  • Example 1:
    • ❌ "notifies downstream atoms or views" - can be understood as it updates only one of them, either atoms or views depending on situation.
    • ✅ "notifies downstream atoms and views": clear that it notifies everything downstream, whether its atom or view.
  • Example 2:
    • ✅ "cancelled by downstream atoms or views", if any atom or view cancelled
    • ❌ "cancelled by downstream atoms and views" all of the downstream atoms and views cancelled
• Some sentences are rephrased.

Remaining potential improvement points:

• Remove pronouns, e.g. "you" → In documentation, might be better avoid using pronouns, e.g.
  • "When you assign a new value" → "When it (atom) is assigned a new value"
  • "A modifier that you apply to an atom" → "A modifier that is applied to an atom"

May be can address them in separate PR

Motivation and Context

To keep documentation up to date and easier to read.

Impact on Existing Code

None

[ra1028]

As for the potential improvement points;

"Parameter atom: An atom that associates the value." (repetitive) → find it confusing, since atoms do associate with value, but not always other way around.

Agreed.
It probably better to have dedicated description per methods while keeping it a very brief description, e.g.

• watch: An atom to be watched.
• read: An atom to read the value

"notifies update to downstream atoms" (repetitive) → can be better without update, or move it to back of the sentence

Agreed to remove update.

Remove pronouns, e.g. "you" → In documentation, might be better avoid using pronouns,

I had the same idea but I vaguely remember that Apple's doc also contains pronouns such as "you" and that's why I used it.
However, I actually don't want to use it in documentation in general so feel free to replace them.

[rasberik]

@ra1028 Thank you! Please review the changes

[ra1028]

Beautiful! 💯 Thank you @rasberik
The changes will automatically be reflected to our documentation page when next tag release.