user-documentation
user-documentation copied to clipboard
hhvm
document argument unpacking (splat) operator "..."
foo($arg1, $arg2, ...$rest);
Provide some examples and describe what's allowed (tuple with enough elements; array only for varargs).
https://github.com/facebook/hhvm/commit/60daa11f227847f2ca71fa37775f285e8122c784 has some good examples
@jjergus I think this is defined here https://docs.hhvm.com/hack/functions/introduction#variadic-functions.
Do you know if there's a way to transclude content so I can just {} the content in that subheading to a new splat (...) page? Or would best practice be to just do a direct link, like https://docs.hhvm.com/hack/expressions-and-operators/async-blocks, where there's just an href.
we don't have a transclude operator, but I can see it as likely being worth adding - but not for that specific section :)
I think it's probably worth adding a dedicated page for 'the splat operator' because there's actually a bunch of them, but most people searching won't know that. It's confusing enough I think it's worth having a dedicated page to just to help external search engines. Various pages should link to (or do a section-transclude if we add support for that) sections of the splat page.
To me, this would be a single page with:
- argument unpacking as described in this task originally
- structural subtyping for shapes (
shape foo('bar' => string, ...)) - XHP attribute splat (
<foo {...$this} />) - 'enum splat': this should link to a page documenting enum inclusion. While enum splat isn't a thing, the concepts are similar, and people are going to search for it
I think this is defined here https://docs.hhvm.com/hack/functions/introduction#variadic-functions.
Good catch, I probably missed that page when I opened this issue. But the important part that's missing there is that the splat operator is not specific to variadic functions. You can use it with any function call, as long as the splatted value is of the correct type (a collection of the correct type for variadic functions; tuple matching all argument types for any function, both variadic and not).
a way to transclude content
I think linking to other pages is almost always better than transcluding content. There should be one canonical place where we document something and all other places should link there. It could be very confusing for people reading the documentation if they start reading some section, only to realize that they've already read the same text somewhere else.
To me, this would be a single page with
Those are all different operators, I don't know if they really should be in a single page just because they have identical/similar syntax. I guess it depends on how the documentation is structured. If there's a "..." page in the "Operators" section, then this probably makes sense. If we decide to keep this in the "functions" guide, then not so much.
just because they have identical/similar syntax.
I think it should be because I think people searching for them are unlikely to realize they're distinct operators :)
I think this is a strong case for a syntax index, the way e.g. Rust does: https://doc.rust-lang.org/1.30.0/book/first-edition/syntax-index.html#operators-and-symbols
... in shapes is pretty different to ... when calling functions, so having an index that links to both shapes and function calls would be a big help.
