Merge pull request rescript-lang#144 from reason-association/update-gentype-docs

Update gentype docs

Author: ryyppy

common/App.js

@@ -18,14 +18,13 @@
   let bash = require('highlight.js/lib/languages/bash');
   let json = require('highlight.js/lib/languages/json');
   let html = require('highlight.js/lib/languages/xml');
-  let ts = require('highlight.js/lib/languages/typescript');
   let text = require('highlight.js/lib/languages/plaintext');
   let diff = require('highlight.js/lib/languages/diff');
 
   hljs.registerLanguage('reason', reason);
   hljs.registerLanguage('res', res);
   hljs.registerLanguage('javascript', js);
-  hljs.registerLanguage('ts', ts);
+  hljs.registerLanguage('ts', js);
   hljs.registerLanguage('ocaml', ocaml);
   hljs.registerLanguage('sh', bash);
   hljs.registerLanguage('json', json);

common/App.res

@@ -8,17 +8,15 @@
 
 **Requirements:**
 
-`bs-platform` 7.0.2 or higher: use `genType` 3.8.0 or higher.
+`bs-platform` 8.3.0 or higher: use `genType` 3.36.0 or higher.
 
-`bs-platform` 7.0.0 or higher: use `genType` 3.2.0 or higher.
+`bs-platform` 8.2.0 or higher: use `genType` 3.31.0 or higher.
 
-`bs-platform` 6.2.0 or higher: use `genType` 3.0.0 or higher.
+`bs-platform` 8.1.1 or higher: use `genType` 3.27.0 or higher.
 
-`bs-platform` 5.2.0 or higher: use `genType` 2.40.0 or higher.
+`bs-platform` 8.0.0 or higher: use `genType` 3.26.0 or higher.
 
-`bs-platform` 5.0.x and 5.1.x: use `genType` 2.17.0 or higher.
-
-For earlier versions, see the older [README](https://github.com/cristianoc/genType/blob/v2.16.0/README.md).
+For earlier versions, check the [genType README requirements section](https://github.com/reason-association/genType#requirements).
 
 </Warn>
 
@@ -44,21 +42,17 @@ Add a `gentypeconfig` section to your `bsconfig.json` (See [Configuration](#conf
 }
 ```
 
-For running `gentype` with BuckleScript via `npm` workflow, add following script in your `package.json`:
+For running `gentype` with ReScript via `npm` workflow, add following script in your `package.json`:
 
 ```
 scripts: {
-  "bs:build": "bsb -make-world",
-  "bs:clean": "bsb -clean-world"
+  "build": "bsb -make-world",
+  "clean": "bsb -clean-world"
 }
 ```
 
 > **Note:** `bsb` will automatically
 > detect your installed `genType` version.
->
-> With genType < 2.17.0 or bucklescript < 5.0.0, one has to set
-> the environment variable `BS_CMT_POST_PROCESS_CMD`. See the older
-> [README](https://github.com/cristianoc/genType/blob/v2.16.0/README.md).
 
 ## Configuration
 
@@ -84,65 +78,51 @@ structure:
   - `"untyped"`: Generate `*.gen.js` files in vanilla JavaScript.
 
 - **shims**
-  - e.g. `Array<string>` with format: `"ReasonModule=JavaScriptModule"`
-  - Required to export certain basic Reason data types to JS when one cannot modify the sources to add annotations (e.g. exporting Reason lists)
+  - e.g. `Array<string>` with format: `"RescriptModule=JavaScriptModule"`
+  - Required to export certain basic ReScript data types to JS when one cannot modify the sources to add annotations (e.g. exporting ReScript lists)
 
 ## Adding Shims (TS & Flow)
 
-Configure your shim files in your `"gentypeconfig"` in
-[`bsconfig.json`](https://github.com/cristianoc/genType/blob/master/examples/typescript-react-example/bsconfig.json), and add
-relevant `.shims.js` files in a directory which is visible by bucklescript e.g.
-[`src/shims/`](https://github.com/cristianoc/genType/blob/master/examples/typescript-react-example/src/shims). An example shim to
-export ReactEvent can be found
-[here](https://github.com/cristianoc/genType/blob/master/examples/typescript-react-example/src/shims/ReactEvent.shim.ts).
+A shim is a TS / Flow file that provides user-defined definitions for library types.
+
+Configure your shim files within `"gentypeconfig"` in your [`bsconfig.json`](https://github.com/reason-association/genType/blob/master/examples/typescript-react-example/bsconfig.json), and add relevant `.shims.js` files in a directory which is visible by ReScript e.g.  [`src/shims/`](https://github.com/reason-association/genType/blob/master/examples/typescript-react-example/src/shims). An example shim to export ReactEvent can be found [here](https://github.com/reason-association/genType/blob/master/examples/typescript-react-example/src/shims/ReactEvent.shim.ts).
 
 ## Testing the Whole Setup
 
-Open any relevant `*.re` file and add `[@genType]` annotations to any bindings
-/ values / functions to be used from JavaScript. If an annotated value uses a
-type, the type must be annotated too. See e.g.
-[Hooks.re](https://github.com/cristianoc/genType/blob/master/examples/typescript-react-example/src/Hooks.re).
+Open any relevant `*.res` file and add `@genType` annotations to any bindings / values / functions to be used from JavaScript. If an annotated value uses a type, the type must be annotated too. See e.g.  [Hooks.res](https://github.com/reason-association/genType/blob/master/examples/typescript-react-example/src/Hooks.res).
 
-Save the file and rebuild the project via `npm run bs:build` or similar. You
-should now see a `*.gen.tsx` (for TypeScript, or `*.gen.js` for Flow) file with
-the same name (e.g. `MyComponent.re` -> `MyComponent.gen.tsx`).
+Save the file and rebuild the project via `npm run bs:build` or similar. You should now see a `*.gen.tsx` (for TypeScript, or `*.gen.js` for Flow) file with the same name (e.g. `MyComponent.res` -> `MyComponent.gen.tsx`).  
 
-Any values exported from `MyComponent.re` can then be imported from JS. For
-example:
+Any values exported from `MyComponent.res` can then be imported from JS. For example:
 
 ```js
 import MyComponent from "./components/MyComponent.gen";
 ```
 
-## Limitations
+## Examples
 
-- **BuckleScript in-source = true**. Currently only supports bucklescript
-projects with [in-source generation](/docs/manual/latest/build-configuration#package-specs) and `.bs.js` file suffix.
+We prepared some examples to give you an idea on how to integrate `genType` in your own project. Check out the READMEs of the listed projects.
 
-- **Limited namespace support**. Currently there's limited [namespace](/docs/manual/latest/build-configuration#name-namespace) support, and only `namespace:true` is possible, not e.g. `namespace:"custom"`.
+**Please make sure to build genType before trying to build the examples.**
 
-## Examples
+- [flow-react-example](https://github.com/reason-association/genType/tree/master/examples/flow-react-example)
+- [typescript-react-example](https://github.com/reason-association/genType/tree/master/examples/typescript-react-example)
+- [untyped-react-example](https://github.com/reason-association/genType/tree/master/examples/untyped-react-example)
 
-We prepared some examples to give you an idea on how to integrate `genType` in
-your own project. Check out the READMEs of the listed projects.
+## Experimental features
 
-- [flow-react-example](https://github.com/cristianoc/genType/tree/master/examples/flow-react-example)
-- [typescript-react-example](https://github.com/cristianoc/genType/tree/master/examples/typescript-react-example)
-- [untyped-react-example](https://github.com/cristianoc/tree/blob/master/examples/untyped-react-example)
+These features are for experimentation only. They could be changed/removed any time, and not be considered breaking changes.
 
-## Experimental features
+- Export object and record types as interfaces. To activate, add `"exportInterfaces": true` to the configuration. The types are also renamed from `name` to `Iname`.
 
-These features are for experimentation only. They could be changed/removed any
-time, and not be considered breaking changes.
+- Emit prop types for the untyped back-end. To activate, add `"propTypes": true` and `"language": "untyped"` to the configuration.
 
-- Export object and record types as interfaces. To activate, add
-`"exportInterfaces": true` to the configuration. The types are also renamed
-from `name` to `Iname`.
+## Limitations
 
-- Emit prop types for the untyped back-end. To activate, add `"propTypes":
-true` and `"language": "untyped"` to the configuration.
+- **in-source = true**. Currently only supports ReScript projects with [in-source generation](/docs/manual/latest/build-configuration#package-specs) and `.bs.js` file suffix.
+
+- **Limited namespace support**. Currently there's limited [namespace](/docs/manual/latest/build-configuration#name-namespace) support, and only `namespace:true` is possible, not e.g. `namespace:"custom"`.
 
 ## Changelog
 
-See [Changes.md](https://github.com/cristianoc/genType/Changes.md) for a
-complete list of features, fixes, and changes for each release.
+See [Changes.md](https://github.com/reason-association/genType/blob/master/Changes.md) for a complete list of features, fixes, and changes for each release.

pages/docs/gentype/latest/getting-started.mdx

@@ -1,77 +1,56 @@
 # GenType
 
-`genType` lets you export [Reason](/docs/manual/latest/introduction) values and
-types to use in JavaScript, and import JavaScript values and types into Reason,
-idiomatically. Converter functions between the two representations are
-generated based on the type of the value. The converters can be generated in
-vanilla JavaScript, or in [TypeScript](https://www.typescriptlang.org/) /
-[Flow](https://flow.org/en/) for a type-safe idiomatic interface. In
-particular, conversion of [ReasonReact](https://reasonml.github.io/reason-react/)
-components both ways is supported, with automatic generation of the wrappers.
-
-Here's an article describing how to use `genType` as part of a migration
-strategy where a tree of components is gradually converted to Reason bottom-up:
-[Adopting Reason: strategies, dual sources of truth, and why genType is a big
-deal](https://www.javierchavarri.com/adopting-reason-strategies-dual-sources-of-truth-and-why-gentype-is-a-big-deal/).
-
-The implementation of [@genType] performs a type-directed transformation of
-Reason programs after ReScript compilation. The
-transformed programs operate on data types idiomatic to JS. For example, a
-Reason function operating on a Reason variant `type t  = | A(int) | B(string)`
-(which is represented as custom blocks at runtime) is exported to a JS function
-operating on the corresponding JS object of type `{ tag: "A"; value: number }
+`genType` is a code generation tool that lets you export ReScript values and types to use in JavaScript, and import JavaScript values and types into ReScript.
+
+Converter functions between the two representations are generated based on the type of the value. The converters can be generated in vanilla JavaScript, or in [TypeScript](https://www.typescriptlang.org/) / [Flow](https://flow.org/en/) for a type-safe idiomatic interface.
+In particular, conversion of [ReasonReact](https://reasonml.github.io/reason-react/) components both ways is supported, with automatic generation of the wrappers.
+
+Here's an article describing how to use `genType` as part of a migration strategy where a tree of components is gradually converted to ReScript bottom-up (old article containing Reason / BuckleScript): [Adopting Reason: strategies, dual sources of truth, and why genType is a big deal](https://medium.com/p/c514265b466d).
+
+The implementation of genType performs a type-directed transformation of ReScript programs after ReScript source code compilation. The transformed programs operate on data types idiomatic to JS.
+
+For example, a ReScript function operating on a ReScript variant `type t  = | A(int) | B(string)` (which is represented as custom blocks at runtime) is exported to a JS function operating on the corresponding JS object of type `{ tag: "A"; value: number }
   | { tag: "B"; value: string }`.
 
-The output of `genType` can be configured by using one of 3 back-ends:
-`untyped` to generate wrappers in vanilla JS, `typescript` to generate
-[TypeScript](https://www.typescriptlang.org/), and `flow` to generate JS with
-[Flow](https://flow.org/en/) type annotations.
+The output of genType can be configured by using one of 3 back-ends: `untyped` to generate wrappers in vanilla JS, `typescript` to generate [TypeScript](https://www.typescriptlang.org/), and `flow` to generate JS with [Flow](https://flow.org/en/) type annotations.
 
-## A More Concrete Example
+## A Quick Example
 
-Let's assume we are working on a TypeScript (TS) codebase and we want to
-integrate a single ReasonReact component.
+Let's assume we are working on a TypeScript (TS) codebase and we want to integrate a single ReasonReact component.
 
-Firstly we want to be able to import the ReasonReact component like any other
-React component, secondly we also want to preserve all the Reason types in the
-TS type system (and convert incompatible values if necessary). **That's what's
-`genType` was made for!**
+We want to be able to import the ReasonReact component like any other React component in our existing TS code, but we also want to preserve all the ReScript types in the TS type system (and convert incompatible values if necessary).
 
+**That's exactly what genType was made for!**
 
-First we'll set up a ReasonReact component just like this (we will assume that
-`genType` and `bs-platform` is already configured correctly):
+First we'll set up a ReasonReact component:
 
-```re
-/* src/MyComp.re */
+```res
+/* src/MyComp.res */
 
-[@genType]
+@genType
 type color =
   | Red
   | Blue;
 
-[@genType]
-[@react.component]
+@genType
+@react.component
 let make = (~name: string, ~color: color) => {
   let colorStr =
     switch (color) {
     | Red => "red"
     | Blue => "blue"
     };
 
-  <div className={"color-" ++ colorStr}> name->React.string </div>;
+  <div className={"color-" ++ colorStr}> {React.string(name)} </div>;
 };
 ```
 
-> **Note:** We need to add a `[@genType]` annotation for `type color` as well,
-otherwise `genType` cannot create any type conversions for us.
-
-On a successful compile, `genType` will convert `MyComp.re` to a TS file called
-`src/MyComp.gen.ts` which will look something like this:
+On a successful compile, `genType` will convert `src/MyComp.res` to a TS file called `src/MyComp.gen.ts` which will look something like this:
 
 ```ts
 // src/MyComp.gen.tsx
 
-/* TypeScript file generated from MyComp.re by genType. */
+/* TypeScript file generated from MyComp.res by genType. */
 /* eslint-disable import/first */
 
 
@@ -95,27 +74,28 @@ export const make: React.ComponentType<{ readonly color: color; readonly name: s
 };
 ```
 
+genType automatically maps the `color` variant to TS via a string union type `color = "Red" | "Blue"`, and also provides all the converters to convert between the ReScript & TS representation as well.
 
-Note how `genType` automatically maps the `color` variant to TS via a string
-union type `color = "Red" | "Blue"`.  We can seamlessly use Reason specific
-data structures within TS without doing any manual transformations!
+Therefore way we can seamlessly use ReScript specific data structures within TS without writing the converter code by hand!
 
-Now, within our TypeScript application, we can now import and use the React
-component in following manner:
+Within our TypeScript application, we can now import and use the React component in the following manner:
 
 ```ts
 // src/App.ts
 import { make as MyComp } from "./MyComp.gen.tsx";
 
 const App = () => {
-  <div>
+  return (<div>
     <h1> My Component </h1>
-    <MyComp color="Blue" name="Reason & TypeScript" />
-  </div>
+    <MyComp color="Blue" name="ReScript & TypeScript" />
+  </div>);
 };
 ```
 
-We are only scratching the surface on what `genType` can actually do. For more
-information, head to the [Getting Started](getting-started) section, or find relevant
-topics from the sidebar !
+That's it for our quick example.
+
+For detailed information, head to the [Getting Started](getting-started) or [Usage](usage) section.
+
+## Development
 
+For contributions, issues or questions, please refer to the [Github repository](https://github.com/reason-association/genType) or our [ReScript forum](https://forum.rescript-lang.org).