Coeffects: be clear about what's being documented in the introduction

[fredemmott]

https://docs.hhvm.com/hack/contexts-and-capabilities/introduction primarily gives examples using hypothetical contexts, and is effectively documentation of the syntax rather than how to actually use it.

While https://docs.hhvm.com/hack/contexts-and-capabilities/local-operations mentions they're hypothetical, this should really be up front - and introduction examples switched to using write_props if practical, so that they are real examples.

Additionally, we should document the real coeffects instead of/as well as the hypothetical ones

https://github.com/facebook/hhvm/blob/master/hphp/hack/src/naming/naming_special_names.rs#L728

---

Please don't change anything below this point.

---

• Build ID: HHVM=HHVM-4.102.0:HSL=v4.94.0:2021-03-30T21:17:53+0000:1fa47f258c6b68f8ec01899aa82fd6ffa0957109
• Page requested: /hack/contexts-and-capabilities/introduction
• Page requested at: Wed, 31 Mar 2021 17:19:34 +0000
• Controller: GuidePageController

[jjergus]

primarily gives examples using hypothetical contexts

The introductory examples with C, C1 etc. are probably fine since those are clearly not real, but the examples with io, rand, throws are indeed confusing since those look very realistic, while only io is actually real.

switched to using write_props if practical

Sadly we only have io as a real context that can be used outside of classes, so we either wouldn't be able to demonstrate using multiple contexts, or we'd have to complicate the introductory examples by putting them into classes...though I guess real examples with classes are still preferable to simpler but not actually real examples.

Additionally, we should document the real coeffects instead of/as well as the hypothetical ones

https://docs.hhvm.com/hack/contexts-and-capabilities/available-contexts-and-capabilities

[fredemmott]

huh, from the tests looks like io is actually real, but it's not in https://github.com/facebook/hhvm/blob/master/hphp/hack/src/naming/naming_special_names.rs#L728 :/