Documentation around code generation

docs/Guide.Contributing.md

@@ -92,3 +92,23 @@ To run the e2e tests, after the application was built.
 ```sh
 npm run e2e
 ```
+
+### Code Generation
+
+We are using a code generator based on `babel` and `objective-c-parser` to generate a Javascript Interface for `EarlGrey` (the testing library we use on iOS).
+This interface allows us to call Objective-C methods through the WebSocket connection directly on the testing device. 
+
+This approach is currently limited to `GREYActions`, but we plan on extending it to cover more functionality of `EarlGrey`.
+You may see the generated files under [`detox/src/ios/earlgreyapi/`](../detox/src/ios/earlgreyapi).
+
+What happens under the hood can be seen in [`generation/`](../generation); it boils down to these steps for each input file:
+
+1. Convert Objective-C header file in a JSON Representation
+2. Build an Abstract Syntax Tree: Create Class & for each method
+    1. Check if the type can be expressed simpler (`NSString *` => `NSString`)
+    2. Get the type checks for the arguments
+    2. Get the return value
+    4. Assemble type checks and return value to complete function
+3. Generate the code for the syntax tree & add helpers
+
+If you would like to extend the code generation, please make sure to read the [`generation/README.md`](../generation#generation)

generation/README.md

@@ -1,9 +1,33 @@
 # Generation
 
 This part of the repository aims to automate the adaption of the underlying testing frameworks.
+For now, it only covers `EarlGrey`'s `GREYActions`.
+
+We chose to check the generated files into version control to have them available as documentation.
+
+To correlate changes to the generation with changes in the generated code, please make sure to run the build before every commit.
 
 ## Development
 
 - `npm install`
 - `npm run build` builds every file specified in the `index.js`
-- `npm test` runs integration level tests
+- `npm test`
+
+## Testing
+
+- We test with integration level tests by having a fixture Objective-C file which we generate and import before the tests.
+- We only add unit tests for code that is used in production, e.g. helper functions. 
+- We then test against this file to ensure that the code generation result works with the specified interface.
+- We decided to base our tests around snapshot tests with the goal to spot mistakes in the return values of the functions without over-specification.
+- If you add functionality that affects the API surface of detox, please also make sure to include [End to End tests for it](../detox/test/e2e).
+
+## Resources
+
+Parsing, ASTs, and code generation are hard topics but don't worry; we got your back.
+Here are some resources that might come in handy:
+
+- [astexplorer](https://astexplorer.net): Allows you to understand Abstract Syntax Trees by showing you code and the resulting AST side-by-side.
+- [Babel Handbook](https://github.com/thejameskyle/babel-handbook):
+- [babel-types](https://github.com/babel/babel/tree/master/packages/babel-types): A builder library for ASTs.
+- [babel-template](https://github.com/babel/babel/tree/master/packages/babel-template): A useful tool we do not use yet for generating bigger ASTs with less code by the usage of string interpolation.
+- [regex101](https://regex101.com): You might need to extract parts of a string; This tool helps you to quickly build the right Regular Expression for the job.