[PR] [DOCS] Add .js.flow documentation

Summary:
Adds documentation on the use of `.flow` files.

Closes #8026
Closes #3609
Pull Request resolved: #8029

Test Plan:
Imported from GitHub, without a `Test Plan:` line.

I inspected the generated website which looks okay.

Reviewed By: gabelevi

Differential Revision: D16993095

Pulled By: panagosg7

fbshipit-source-id: 9ab349a4e19820e22c33d9264069f5ea02cd7cce

website/_data/guides.yml

@@ -103,6 +103,14 @@
     - path: "/docs/libdefs/"
     # - path: "/docs/libdefs/usage/"
     - path: "/docs/libdefs/creation/"
+      additional_reading:
+        - guide: declarations
+
+- id: declarations
+  pages:
+    - path: "/docs/declarations/"
+      additional_reading:
+        - guide: libdefs
 
 # - id: errors
 #   pages:

website/_data/i18n/en.yml

@@ -218,6 +218,9 @@ docs_additional_reading: "Additional Reading"
 "/docs/libdefs/usage/":
   title: "Using Library Definitions"
   description: ""
+"/docs/declarations/":
+  title: "Declaration Files"
+  description: "Using .flow files"
 "/docs/modules/":
   title: "Modules"
   description: ""
@@ -426,6 +429,10 @@ guides:
     description: >
       Learn how to create and use library definitions for the third-party code
       your code depends on.
+  declarations:
+    title: "Declaration Files"
+    description: >
+      Learn how to write types in .flow files.
   # errors:
   #   title: "Debugging Errors"
   #   description: >

website/en/docs/declarations/index.md

@@ -0,0 +1,88 @@
+---
+layout: guide
+---
+
+## What's a Declaration File? <a class="toc" id="toc-what-s-a-declaration-file" href="#toc-what-s-a-declaration-file"></a>
+
+Let's look at a more general, and sometimes more convenient way to
+declare types for modules: `.flow` files.
+
+There are two possible use cases, depending on whether an implementation file exists
+or not.
+
+In the first case, the exported types of a module are declared in a _declaration
+file_ `<FILENAME>.flow`, that is located in the same directory as the corresponding _implementation
+file_ `<FILENAME>`. The declaration file completely shadows the colocated
+implementation. In other words, Flow will completely ignore `<FILENAME>` and just
+read `<FILENAME>.flow` instead.
+
+In the second case, the implementation file is missing entirely. `<FILENAME>.flow`
+is treated as if it is named `<FILENAME>`.
+
+Note that the `.flow` extension applies both to `.js` files as well as `.json`
+ones. The corresponding declaration files have extensions `.js.flow` and `.json.flow`,
+respectively.
+
+Now let's see an example of the first case documented above. Suppose we have the
+following code in a file `src/LookBeforeYouLeap.js`:
+
+```js
+// @flow
+import { isLeapYear } from "./Misc";
+if (isLeapYear("2020")) console.log("Yay!");
+```
+
+and suppose that `src/Misc.js` has an incompatible implementation of `isLeapYear`:
+
+```js
+// @flow
+export function isLeapYear(year: number): boolean {
+  return year % 4 == 0; // yeah, this is approximate
+}
+```
+
+If we now create a declaration file `src/Misc.js.flow`, the declarations in it
+will be used instead of the code in `src/Misc.js`. Let's say we have the
+following declarations in `src/Misc.js.flow`.
+
+> NOTE: The syntax for declarations in a declaration file is the same as we've seen in
+>       [Creating Library Definitions section](../libdefs/creation).
+
+```js
+// @flow
+declare export function isLeapYear(year: string): boolean;
+```
+
+What do you think will happen?
+
+Right, the `isLeapYear` call in `src/LookBeforeYouLeap.js` will typecheck, since
+the `year` parameter expects a `string` in the declaration file.
+
+As this example shows, declaration files must be written with care: it is up
+to the programmer to ensure they are correct, otherwise they may hide type
+errors.
+
+
+## Inlining declarations in regular code <a class="toc" id="toc-inlining-declarations-in-regular-code" href="#toc-inlining-declarations-in-regular-code"></a>
+
+Sometimes it is useful to make declarations inline, as part of the source of
+an implementation file.
+
+In the following example, say you want to finish writing
+the function `fooList` without bothering to mock up its dependencies first: a
+function `foo` that takes a `number` and returns a `string`, and a class
+`List` that has a `map` method. You can do this by including declarations for
+`List` and `foo`:
+
+```js
+declare class List<T> {
+  map<U>(f: (x: T) => U): List<U>;
+}
+declare function foo(n: number): string;
+
+function fooList(ns: List<number>): List<string> {
+  return ns.map(foo);
+}
+```
+
+Just don't forget to replace the declarations with proper implementations.

website/en/docs/libdefs/creation.md

@@ -89,8 +89,7 @@ declare module "some-third-party-library" {
 The name specified in quotes after `declare module` can be any string, but it
 should correspond to the same string you'd use to `require` or `import` the
 third-party module into your project. For defining modules that are accessed via
-a relative `require`/`import` path, please see the docs on the `.js.flow` files 
-which will be available soon.
+a relative `require`/`import` path, please see the docs on the [`.flow` files](../declarations)
 
 Within the body of a `declare module` block, you can specify the set of exports
 for that module. However, before we start talking about exports we have to talk