user-documentation
user-documentation copied to clipboard
hhvm
Clarify that "Arrays" documentation includes vec, dict, and keyset
I fielded an internal question at Slack about how to append objects to vecs, and more generally where to find this information in the docs. I pointed to https://docs.hhvm.com/hack/built-in-types/arrays, which explains how to do $colors = vec[]; $colors[] = 'red';.
It's a little confusing to expect people to click into the "Arrays" section to find information about how to use vec/dict/keyset, especially if they have heard that PHP arrays are being replaced with something else.
Maybe move the vec/dict/keyset information to a separate page, or include them in the name of this one?
Seems reasonable, that page is way too long anyway so probably worth splitting.
The name 'hack arrays' itself seems like a PHPism when it includes 'dict' - unfortunately 'collections' is already taken :(
That also seems unwise as there's a Container type. I fear we've exhausted all the obvious names.
"Containers" seems fine to me but also we could just call it "vec, dict, keyset" or even "Containers (vec, dict, keyset)" if there's enough space.
"Containers" page could also briefly mention the interfaces (Container, Traversable, Keyed...); I think we previously covered that as part of the documentation about collections.
Seems reasonable, that page is way too long anyway so probably worth splitting.
This is increasingly seeming like the right approach to me - perhaps:
- separate pages for each of vec, dict, and keyset
- separate page for the cheat sheet
- another, shared page for all 'legacy containers'
The page has received an update since this issue was filed. It now starts with:
Hack includes diverse range of array-like data structures.
Hack arrays are value types for storing iterable data. The types available are vec, dict and keyset. When in doubt, use Hack arrays.
Closing this issue, but feel free to file another if I've missed something from the conversation.
