fixes from reviewers

guides/hack/21-XHP/01-introduction.md

@@ -13,7 +13,8 @@ However, with XHP, it looks like this:
 
 ```
 $user_name = 'Fred';
-echo <tt>Hello <strong>{$user_name}</strong></tt>;
+$xhp = <tt>Hello <strong>{$user_name}</strong></tt>;
+echo await $xhp->toStringAsync();
 ```
 
 The first example uses string interpolation to output the HTML, while the second has no quotation marks&mdash;meaning that the syntax is

guides/hack/21-XHP/04-setup.md

@@ -38,12 +38,8 @@ whether XHP namespace support is enabled in your HHVM version.
 
 While the XHP syntax is part of Hack, a large part of the implementation is in a
 library called [XHP-Lib](https://github.com/hhvm/xhp-lib/) that needs to be
-installed via composer; add `xhp-lib` to your `composer.json`, e.g:
-
-```
-$ composer require facebook/xhp-lib
-# note: make sure to use PHP, not HHVM, to execute composer
-```
+installed via Composer (add `facebook/xhp-lib` to your `composer.json` manually
+or by running `composer require facebook/xhp-lib ^4.0` or `^3.0`).
 
 This includes the base classes and interfaces, and definitions of standard HTML elements.
 
@@ -63,3 +59,6 @@ There are currently two major supported versions of XHP-Lib:
 All the following guides are written with the assumption that XHP namespace
 support is enabled and XHP-Lib v4 is used, but there are notes pointing out any
 major differences—look for **Historical note** sections.
+
+<span class="fbOnly fbIcon">XHP namespaces are not enabled in Facebook's WWW
+repository, so all **Historical note** sections apply.</span>

guides/hack/21-XHP/07-basic-usage.md

@@ -12,7 +12,9 @@ $my_xhp_object = <p>Hello, world</p>;
 `$my_xhp_object` now contains an instance of the `p` class.
 It is a real object, meaning that `is_object` will return `true` and you can call methods on it.
 
-**Historical note:** Before XHP namespace support (in XHP-Lib v3), XHP classes
+**Historical note:**
+<span class="fbOnly fbIcon">(applies in FB WWW repository)</span>
+Before XHP namespace support (in XHP-Lib v3), XHP classes
 lived in a separate (but still global) namespace from regular classes, denoted
 by a `:` prefix in the typechecker and an `xhp_` prefix at runtime. `<p>` would
 therefore instantiate a class named `:p` in Hack code and `xhp_p` at runtime. It
@@ -66,7 +68,9 @@ $class_name = Facebook\XHP\HTML\p::class;
 final xhp class my_element extends \Facebook\XHP\Core\element { ... }
 ```
 
-**Historical note:** Before XHP namespace support (in XHP-Lib v3), `:` is
+**Historical note:**
+<span class="fbOnly fbIcon">(applies in FB WWW repository)</span>
+Before XHP namespace support (in XHP-Lib v3), `:` is
 allowed as part of an XHP class name, but it is *not* a namespace separator. It
 is simply translated to `__` at runtime (this is called "name mangling"). For
 example, `<ui:table>` would instantiate a global class named `xhp_ui__table`. In
@@ -101,11 +105,12 @@ class defines what attributes are available to objects of that class:
 echo <input type="button" name="submit" value="OK" />;
 ```
 
-Here the `input` class has the attributes `type`, `name` and `value` as part of its class properties.
+Here the `input` class has the attributes `type`, `name` and `value`.
 
-Some attributes are required, and XHP will throw an error if you use an XHP object with a required attribute but without the attribute. Depending on the exact HHVM
-version and configuration, this may or may not be a typechecker error, but is
-always a runtime error.
+Some attributes are required, and XHP will throw an exception when an XHP object
+is rendered (`toStringAsync()` is called) with any required attributes missing.
+With `check_xhp_attribute=true` (available since HHVM 4.8) this is also a
+typechecker error.
 
 ## HTML Character References
 

guides/hack/21-XHP/10-interfaces.md

@@ -28,7 +28,9 @@ one of its two subclasses:
   a `stringifyAsync()` method that returns a `string` and must manually deal with
   any children
 
-**Historical note:** Before XHP namespace support (in XHP-Lib v3), the names of
+**Historical note:**
+<span class="fbOnly fbIcon">(applies in FB WWW repository)</span>
+Before XHP namespace support (in XHP-Lib v3), the names of
 `node`, `element` and `primitive` are `\XHPRoot`, `:x:element` and
 `:x:primitive` respectively.
 
@@ -47,7 +49,9 @@ XHP usually gets in the way of this by:
 
 The `\Facebook\XHP\UnsafeRenderable` and `\Facebook\XHP\XHPAlwaysValidChild` interfaces allow bypassing these safety mechanisms.
 
-**Historical note:** Before XHP namespace support (in XHP-Lib v3), the names of
+**Historical note:**
+<span class="fbOnly fbIcon">(applies in FB WWW repository)</span>
+Before XHP namespace support (in XHP-Lib v3), the names of
 these interfaces are `\XHPUnsafeRenderable` and `\XHPAlwaysValidChild`.
 
 ### `\Facebook\XHP\UnsafeRenderable`

guides/hack/21-XHP/16-extending.md

@@ -6,7 +6,9 @@ items that are not in the standard HTML specification.
 XHP class names must follow the same rules as any other Hack class names:
 Letters, numbers and `_` are allowed and the name mustn't start with a number.
 
-**Historical note:** Before XHP namespace support (in XHP-Lib v3), XHP class
+**Historical note:**
+<span class="fbOnly fbIcon">(applies in FB WWW repository)</span>
+Before XHP namespace support (in XHP-Lib v3), XHP class
 names could also contain `:` (now a namespace separator) and `-` (now disallowed
 completely). These were translated to `__` and `_` respectively at runtime (this
 is called "name mangling"). For example, `<ui:big-table>` would instantiate a
@@ -22,7 +24,9 @@ A custom XHP class needs to do three things:
 @@ extending-examples/basic.inc.php @@
 @@ extending-examples/basic.php @@
 
-**Historical note:** Before XHP namespace support (in XHP-Lib v3), use
+**Historical note:**
+<span class="fbOnly fbIcon">(applies in FB WWW repository)</span>
+Before XHP namespace support (in XHP-Lib v3), use
 `class :intro_plain_str` instead of `xhp class intro_plain_str` (no `xhp`
 keyword, but requires a `:` prefix in the class name).
 
@@ -87,15 +91,22 @@ You can declare the types that your custom class is allowed to have as children
 by using the `Facebook\XHP\ChildValidation\Validation` trait and implementing the
 `getChildrenDeclaration()` method.
 
-**Historical note:** Before XHP namespace support (in XHP-Lib v3), a special
+**Historical note:**
+<span class="fbOnly fbIcon">(applies in FB WWW repository)</span>
+Before XHP namespace support (in XHP-Lib v3), a special
 `children` keyword with a regex-like syntax could be used instead
 ([examples](https://github.com/hhvm/xhp-lib/blob/v3.x/tests/ChildRuleTest.php)).
 However, XHP-Lib v3 also supports `Facebook\XHP\ChildValidation\Validation`, and
 it is therefore recommended to use it everywhere.
 
 If you don't use the child validation trait, then your class can have any
-children. If you try to add a child to an object
-that doesn't allow one or it doesn't exist in its declaration list, then an `InvalidChildrenException` will be thrown during rendering.
+children. However, child validation still applies to any XHP objects returned
+by your `renderAsync()` method that use the trait.
+
+If an element is rendered (`toStringAsync()` is called) with children that don't
+satisfy the rules in its `getChildrenDeclaration()`, an `InvalidChildrenException`
+is thrown. Note that child validation only happens during rendering, no
+exception is thrown before that, e.g. when the invalid child is added.
 
 @@ extending-examples/children.inc.php @@
 @@ extending-examples/children.php @@
@@ -113,7 +124,9 @@ of which may not even exist yet.
 @@ extending-examples/categories.inc.php @@
 @@ extending-examples/categories.php @@
 
-**Historical note:** Before XHP namespace support (in XHP-Lib v3), a special
+**Historical note:**
+<span class="fbOnly fbIcon">(applies in FB WWW repository)</span>
+Before XHP namespace support (in XHP-Lib v3), a special
 `category` keyword could be used instead of an interface
 (`category %name1, %name2;`).
 
@@ -127,7 +140,9 @@ functions and use `await`.
 @@ extending-examples/xhp-async.inc.php @@
 @@ extending-examples/xhp-async.php @@
 
-**Historical note:** In XHP-Lib v3, most rendering methods are not async, and
+**Historical note:**
+<span class="fbOnly fbIcon">(applies in FB WWW repository)</span>
+In XHP-Lib v3, most rendering methods are not async, and
 therefore a special `\XHPAsync` trait must be used in XHP classes that need to
 `await` something during rendering.
 
@@ -137,7 +152,9 @@ The `Facebook\XHP\HTML\XHPHTMLHelpers` trait implements two behaviors:
 * Giving each object a unique `id` attribute.
 * Managing the `class` attribute.
 
-**Historical note:** In XHP-Lib v3, this trait is called `\XHPHelpers`.
+**Historical note:**
+<span class="fbOnly fbIcon">(applies in FB WWW repository)</span>
+In XHP-Lib v3, this trait is called `\XHPHelpers`.
 
 ### Unique IDs
 
@@ -151,7 +168,7 @@ parts of your code or UI framework (e.g., CSS).
 
 `XHPHTMLHelpers` has two methods to add a class name to the `class` attribute of
 an XHP object. `addClass` takes a `string` and appends that `string` to the
-`class` attribute; `conditionClass` takes a `bool` and a `string`, and only
+`class` attribute (space-separated); `conditionClass` takes a `bool` and a `string`, and only
 appends that `string` to the `class` attribute if the `bool` is `true`.
 
 This is best illustrated with a standard HTML element, all of which have a
@@ -183,5 +200,7 @@ This can be addressed by using the `XHPAttributeClobbering_DEPRECATED` trait.
 Now, when `<ui:my-custom>` is rendered, each `<div>` attribute will be transferred over.
 Also, any explicitly set `<ui:my-custom>` attribute value will override the same `<div>` attribute set in the `render` function.
 
-**Historical note:** In XHP-Lib v3, this is provided by the `\XHPHelpers` trait
+**Historical note:**
+<span class="fbOnly fbIcon">(applies in FB WWW repository)</span>
+In XHP-Lib v3, this is provided by the `\XHPHelpers` trait
 instead of a separate one.

guides/hack/21-XHP/19-migration.md

@@ -4,8 +4,8 @@ Assume your output is currently handled by the following function, which might
 be called from many places.
 
 ```Hack
-function render_component($text, $uri) {
-  $uri = htmlspecialchars($uri);
+function render_component(string $text, Uri $uri): string {
+  $uri = htmlspecialchars($uri->toString());
   $text = htmlspecialchars($text);
   return "<a href=\"$uri\">$text</a>";
 }
@@ -16,8 +16,8 @@ function render_component($text, $uri) {
 You can start by simply using XHP in `render_component`:
 
 ```Hack
-async function render_component($text, $uri) {
-  $link = <a href={$uri}>{$text}</a>;
+async function render_component(string $text, Uri $uri): Awaitable<string> {
+  $link = <a href={$uri->toString()}>{$text}</a>;
   return await $link->toStringAsync();
   // or HH\Asio\join if converting all callers to async is hard
 }
@@ -34,11 +34,11 @@ You could make `render_component` into a class:
 namespace ui;
 
 class link extends x\element {
-  attribute Uri $uri @required;  // Assume class Uri
-  attribute string $text @required;
+  attribute Uri uri @required;
+  attribute string text @required;
   protected async function renderAsync(): Awaitable<x\node> {
     return
-      <a href={$this->:uri}>{$this->:text}</a>;
+      <a href={$this->:uri->toString()}>{$this->:text}</a>;
   }
 }
 ```

sass/basics.scss

@@ -51,7 +51,8 @@ a {
   padding-left: 1em;
   font-style: italic;
 }
-.fbOnly.apiAlias:before {
+
+.fbOnly.apiAlias:before, .fbIcon:before {
   content: 'f';
   margin-right: 0.25em;
   font-style: normal;