Github's markdown renderer requires a space between the #s and the header.

This also fixes internal section links, since the renderer wasn't creating anchors for the unrendered headers.

compare (e.g.) https://github.com/hhvm/hack-langspec/blob/master/spec/05-types.md https://github.com/nelhage/hack-langspec/blob/fix-markdown/spec/05-types.md

https://github.com/hhvm/hack-langspec/blob/master/spec/14-generic-types-methods-and-functions.md#open-and-closed-generic-types

I'm not sure why this distinction is being made at all, actually.

Each closed generic type, method, or function has its own set of static variables, which are not shared with any other closed generic types, methods, or functions.

I read this to mean that Blah<int> and Blah<string> don't share statics, which I'm fairly certain is incorrect (given our runtime type erasure semantics).

https://github.com/hhvm/hack-langspec/blob/master/spec/10-expressions.md#expressions should probably mention await. Might be missing in other syntax specifiers too.

When an async function is compiled, a special transformation is performed, so that an object that implements Awaitable (§§) is returned to the caller (where T is the function's return-type).

Need to check the definition of return-type, but this transform happens at runtime, the static return type is still always Awaitable<T>, that's what you write down in the source file.

When yielding control, the implementation of await may choose to yield control back to the current async function's caller.

Not sure what this is getting at here since the caller is still blocked.

https://github.com/hhvm/hack-langspec/blob/master/spec/05-types.md#general makes a distinction between value types and handle types, and I have no idea what it's getting at. I thought we decided to drop any distinction between types like this, in favor of just the subtype relation?

We talk about strict in the spec, but you cannot have a call to a top-level function in strict. You currently have to have some sort of non-strict initializer file that gets included in the strict file that calls something like main() for example.

• Make shapes first-class types
• Remove erroneous integer-literal as field key
• Mention nullable fields
• Mention shape subtyping
• Support assignment of shapes
• Add predefined class Shapes
• Support all the Shape grammar changes
• Make Shapes a final class in the declaration and remove the equivalent narrative

From the handful of occurrences of "Arr-D" in the spec, I don't see any way "Arr-D" should be distinguishable from "Arr" (IIRC the wording rather suggests it shouldn't be). In that case, it would be a mere implementation detail, so why mention it at all? One could even discuss whether the entire copy-on-write has a purpose when describing the semantics of Hack. I was surprised since at the same time the spec seems fairly liberal about related concepts like memory management or object lifetime; reads like some bits of a runtime spec/doc have found their way into a language spec. 🙂

Maybe I missed some details but running the tests (in tests folder) with fresh HHVM does not yield the expected results in all cases (e.g. errors out on negative shift, different output in several cases). Was the idea to have the spec model HHVM or have HHVM follow the spec? I think for some of the discrepancies I saw, HHVM is actually behaving the same as PHP, so I get it if that is behavior that HHVM users rely on.

Looking at the expected output, I assume the tests were meant to test for over-/underflow behavior, so I switched the order of inc/dec accordingly. Note that the expected output was then also perfectly swapped ("pre" behavior in "post" output and vice versa).

No example is provided for type-specification usage, so I add one. Overuse of base-type exposure through type-specifications has led to significant lost time and typing errors, so it makes sense to be clear about how it works. The best use case for base-type exposure is when a "raw" int or string is being migrated to be an Enum. The best practice, after a migration, is to explicitly cast the enum value to the base type whenever this is necessary.

With the original wording, it's hard to tell whether __FILE__ refers to just the last component of the path (sometimes called the name of a file) or the complete path.