Update non-mutation documentation

Summary: * Update non-mutation documentation in preparation for updating mutation documentation

Reviewed By: alunyov

Differential Revision: D33921087

fbshipit-source-id: 6446b3295e537adc0918451c1bedeb08f974d2a3

Author: rbalicki2

.github/CONTRIBUTING.md

@@ -62,7 +62,7 @@ We will eventually have a linter that will catch most styling issues that may ex
 
 ## Development process for non-FB developers
 
-A typical solution for working on a library is to test changes in your application project through ‘linking’. The
+A typical solution for working on a library is to test changes in your application project through 'linking’. The
 following steps should work for all Relay packages:
 
 1. Either trigger a build manually by running `yarn build` or keep a watcher running with `yarn build:watch`.

meta/meeting-notes/2016-12-09-update.md

@@ -2,7 +2,7 @@
 
 It's been a while since our last meeting notes, thanks for your patience!
 
-Over the last couple of months we've been focusing on building an experimental new core (that we've referred to as Relay "2") and integrating it into products internally. During this process we've refined the new apis, fixed bugs, added missing features, and worked to confirm our hypothesis that the more static core could bring performance improvements on mobile devices. The results so far are promising and we're continuing to pursue this direction.
+Over the last couple of months we've been focusing on building an experimental new core (that we've referred to as Relay "2") and integrating it into products internally. During this process we've refined the new APIs, fixed bugs, added missing features, and worked to confirm our hypothesis that the more static core could bring performance improvements on mobile devices. The results so far are promising and we're continuing to pursue this direction.
 
 We've also established a migration pathway for products currently using Relay. Over the next few months we'll be deprecating the current APIs (e.g. `RelayContainer`) and introducing a new product API: slimmed down evolutions of the `RelayRenderer`/`RelayRootContainer`, `RelayContainer`, `RelayMutation`, etc. Products can incrementally migrate to the new APIs, which are simpler and more predictable on their own. When fully converted, products can then toggle a switch to enable the experimental core, unlocking performance optimizations and new features such as persisted queries.
 

website/docs/guided-tour/managing-data-outside-react/retaining-queries.md

@@ -43,7 +43,9 @@ const disposable = environment.retain(queryDescriptor);
 disposable.dispose();
 ```
 
-> NOTE: Relay automatically manages the query data retention based on any mounted query components that are rendering the data, so you usually should not need to call retain directly within product code. For any advanced or special use cases, query data retention should usually be handled within infra-level code, such as a Router.
+:::note
+Relay automatically manages the query data retention based on any mounted query components that are rendering the data, so you usually should not need to call retain directly within product code. For any advanced or special use cases, query data retention should usually be handled within infra-level code, such as a Router.
+:::
 
 
 <DocsRating />

website/docs/guided-tour/refetching/refetching-fragments-with-different-data.md

@@ -75,12 +75,12 @@ Let's distill what's happening in this example:
 
 * `useRefetchableFragment` behaves similarly to [`useFragment`](../../../api-reference/use-fragment/) (see the [Fragments](../../rendering/fragments/) section), but with a few additions:
     * It expects a fragment that is annotated with the `@refetchable` directive. Note that `@refetchable` directive can only be added to fragments that are "refetchable", that is, on fragments that are on `Viewer`, on `Query`, on any type that implements `Node` (i.e. a type that has an `id` field), or on a [`@fetchable`](https://fb.workplace.com/groups/graphql.fyi/permalink/1539541276187011/) type.
-* It returns a `refetch` function, which is already  Flow typed to expect the query variables that the generated query expects.
+* It returns a `refetch` function, which is already Flow-typed to expect the query variables that the generated query expects.
 * It takes two Flow type parameters: the type of the generated query (in our case  `CommentBodyRefetchQuery`), and a second type which can always be inferred, so you only need to pass underscore (`_`).
 * We're calling the `refetch` function with 2 main inputs:
     * The first argument is the set of variables to fetch the fragment with. In this case, calling `refetch` and passing a new set of variables will fetch the fragment again *with the newly provided variables*. The variables you need to provide are a subset of the variables that the `@refetchable` query expects; the query will require an `id`, if the type of the fragment has an `id` field, and any other variables that are transitively referenced in your fragment.
         * In this case we're passing the current comment `id` and a new value for the `translationType` variable to fetch the translated comment body.
-    * We are not passing a second options argument in this case, which means that we will use the default `fetchPolicy` of `‘store-or-network'`, which will skip the network request if the new data for that fragment is already cached (as we covered in [Reusing Cached Data For Render](../../reusing-cached-data/)).
+    * We are not passing a second options argument in this case, which means that we will use the default `fetchPolicy` of `'store-or-network'`, which will skip the network request if the new data for that fragment is already cached (as we covered in [Reusing Cached Data For Render](../../reusing-cached-data/)).
 * Calling `refetch` will re-render the component and may cause `useRefetchableFragment` to suspend (as explained in [Loading States with Suspense](../../rendering/loading-states/)). This means that you'll need to make sure that there's a `Suspense` boundary wrapping this component from above in order to show a fallback loading state.
 
 </OssOnly>

website/docs/guided-tour/refetching/refreshing-fragments.md

@@ -94,7 +94,7 @@ Let's distill what's happening in this example:
 
 * `useRefetchableFragment` behaves similarly to [`useFragment`](../../../api-reference/use-fragment/) (see the [Fragments](../../rendering/fragments/) section), but with a few additions:
     * It expects a fragment that is annotated with the `@refetchable` directive. Note that  `@refetchable` directive can only be added to fragments that are "refetchable", that is, on fragments that are on `Viewer`, on `Query`, on any type that implements `Node` (i.e. a type that has an `id` field).
-* It returns a `refetch` function, which is already Flow typed to expect the query variables that the generated query expects
+* It returns a `refetch` function, which is already Flow-typed to expect the query variables that the generated query expects
 * It takes two Flow type parameters: the type of the generated query (in our case  `UserComponentRefreshQuery`), and a second type which can always be inferred, so you only need to pass underscore (`_`).
 * We're calling the `refetch` function with 2 main inputs:
     * The first argument is the set of variables to fetch the fragment with. In this case, calling `refetch` and passing an empty set of variables will fetch the fragment again *with the exact same variables the fragment was originally fetched with,* which is what we want for a refresh.

website/docs/guided-tour/rendering/fragments.md

@@ -87,11 +87,12 @@ module.exports = UserComponent;
 Let's distill what's going on here:
 
 * `useFragment` takes a fragment definition and a *fragment reference*, and returns the corresponding `data` for that fragment and reference.
+  * This is similar to `usePreloadedQuery`, which takes a query definition and a query reference.
 * A *fragment reference* is an object that Relay uses to *read* the data declared in the fragment definition; as you can see, the `UserComponent_user` fragment itself just declares fields on the `User` type, but we need to know *which* specific user to read those fields from; this is what the fragment reference corresponds to. In other words, a fragment reference is like *a pointer to a specific instance of a type* that we want to read data from.
 * Note that *the component is automatically subscribed to updates to the fragment data*: if the data for this particular `User` is updated anywhere in the app (e.g. via fetching new data, or mutating existing data), the component will automatically re-render with the latest updated data.
 * Relay will automatically generate Flow types for any declared fragments when the compiler is run, so you can use these types to declare the type for your Component's `props`.
     * The generated Flow types include a type for the fragment reference, which is the type with the `$key` suffix: `<fragment_name>$key`, and a type for the shape of the data, which is the type with the `$data` suffix:  `<fragment_name>$data`; these types are available to import from files that are generated with the following name: `<fragment_name>.graphql.js`.
-    * We use our [lint rule](https://github.com/relayjs/eslint-plugin-relay) to enforce that the type of the fragment reference prop is correctly declared when using `useFragment`. By using a properly typed fragment reference as input, the type of the returned `data` will automatically be Flow typed without requiring an explicit annotation.
+    * We use our [lint rule](https://github.com/relayjs/eslint-plugin-relay) to enforce that the type of the fragment reference prop is correctly declared when using `useFragment`. By using a properly typed fragment reference as input, the type of the returned `data` will automatically be Flow-typed without requiring an explicit annotation.
     * In our example, we're typing the `user` prop as the fragment reference we need for `useFragment`, which corresponds to the `UserComponent_user$key` imported from  `UserComponent_user.graphql`, which means that the type of `data` above would be: `{ name: ?string, profile_picture: ?{ uri: ?string } }`.
 * Fragment names need to be globally unique. In order to easily achieve this, we name fragments using the following convention based on the module name followed by an identifier: `<module_name>_<property_name>`. This makes it easy to identify which fragments are defined in which modules and avoids name collisions when multiple fragments are defined in the same module.
 
@@ -259,7 +260,11 @@ There are a few things to note here:
 
 * `UserComponent` both renders `UsernameSection`, *and* includes the fragment declared by `UsernameSection` inside its own `graphql` fragment declaration.
 * `UsernameSection` expects a *fragment reference* as the `user` prop. As we've mentioned before, a fragment reference is an object that Relay uses to *read* the data declared in the fragment definition; as you can see, the child `UsernameSection_user` fragment itself just declares fields on the `User` type, but we need to know *which* specific user to read those fields from; this is what the fragment reference corresponds to. In other words, a fragment reference is like *a pointer to a specific instance of a type* that we want to read data from.
-*  Note that in this case the `user` passed to `UsernameSection`, i.e. the fragment reference, *doesn't actually contain any of the data declared by the child `UsernameSection` component*; instead, `UsernameSection` will use the fragment reference to read the data *it* declared internally, using `useFragment`. This prevents the parent from implicitly creating dependencies on data declared by its children, and vice-versa, which allows us to reason locally about our components and modify them without worrying about affecting other components. If this wasn't the case, and the parent had access to the child's data, modifying the data declared by the child could break the parent. This is known as [*data masking*](../../../principles-and-architecture/thinking-in-relay/).
+*  Note that in this case the `user` passed to `UsernameSection`, i.e. the fragment reference, *doesn't actually contain any of the data declared by the child `UsernameSection` component*; instead, `UsernameSection` will use the fragment reference to read the data *it* declared internally, using `useFragment`.
+  * This means that the parent component will not receive the data selected by a child component (unless that parent explicitly selected the same fields). Likewise, child components will not receive the data selected by their parents (again, unless the child selected those same fields).
+  * This prevents separate components from *even accidentally* having implicit dependencies on each other. If this wasn't the case, modifying a component could break other components!
+  * This allows us to reason locally about our components and modify them without worrying about affecting other components.
+  * This is known as [*data masking*](../../../principles-and-architecture/thinking-in-relay/).
 * The *fragment reference* that the child (i.e.  `UsernameSection`) expects is the result of reading a parent fragment that *includes* the child fragment. In our particular example, that means the result of reading a fragment that includes `...UsernameSection_user` will be the fragment reference that `UsernameSection` expects. In other words, the data obtained as a result of reading a fragment via `useFragment` also serves as the fragment reference for any child fragments included in that fragment.
 
 

website/docs/guided-tour/rendering/loading-states.md

@@ -114,7 +114,7 @@ const {Suspense} = require('React');
 
 function App() {
   return (
-    // A LoadingGlimmer for *_all_* content is rendered via the Suspense fallback
+    // A LoadingGlimmer for all content is rendered via the Suspense fallback
     <Suspense fallback={<LoadingGlimmer />}>
       <MainContent />
       <SecondaryContent /> {/* SecondaryContent can also suspend */}