Add documentation

Author: gaeljw

README.md

@@ -42,3 +42,10 @@ Any contribution is welcome:
 - developing a new feature
 
 Please use this Github project for contributing, either through an issue or a Pull Request.
+
+### Documentation
+
+These pages aim to help Cucumber Scala developers understand the codebase.
+
+- [Scala implementation details](docs/scala_implementation.md)
+- [Project structure](docs/project_structure.md)

docs/project_structure.md

@@ -0,0 +1,50 @@
+# Project structure
+
+The Cucumber Scala project is a Maven multimodule project:
+- `scala` module: contains the codebase of the Cucumber Scala implementation
+  - `scala_2.11` submodule: build for Scala 2.11.x
+  - `scala_2.12` submodule: build for Scala 2.12.x
+  - `scala_2.13` submodule: build for Scala 2.13.x
+- `examples` module: contains a sample project 
+
+## Cross compilation
+
+The cross compilation for the different Scala versions is handled with 3 different Maven projects: the submodules of the `scala` module.
+
+Each project has a different Scala version as dependency:
+```xml
+<dependency>
+    <groupId>org.scala-lang</groupId>
+    <artifactId>scala-compiler</artifactId>
+    <version>${scala.2.13.version}</version>
+    <scope>provided</scope>
+</dependency>
+```
+
+To not copy/paste the sources across the 3 projects, the sources are put in a separated folder called `sources` in the `scala` module.
+Each project uses it by defining the following properties:
+```xml
+<sourceDirectory>../sources/src/main/scala</sourceDirectory>
+<resources>
+    <resource>
+        <directory>../sources/src/main/resources</directory>
+    </resource>
+</resources>
+<testSourceDirectory>../sources/src/test/scala</testSourceDirectory>
+<testResources>
+    <testResource>
+        <directory>../sources/src/test/resources</directory>
+    </testResource>
+</testResources>
+```
+
+**Note:** when using your favorite IDE, you might have to "close" or "unload" 2 of the 3 projects.
+Some IDE are not able to handle shared sources because a source path can be attached to a single IDE project.
+If so, only loading the latest (`scala_2.13` project) is recommended.
+
+## Language traits generation
+
+The language traits (`io.cucumber.scala.EN` for instance) are generated automatically using
+a Groovy script at compile time.
+
+See in `sources/src/main/groovy/` folder.

docs/scala_implementation.md

@@ -0,0 +1,59 @@
+# Scala implementation details
+
+This page covers some details about the Cucumber Scala implementation.
+
+## Running a Cucumber test
+
+### Backend
+
+From Cucumber core perspective, the entrypoint of a Cucumber implementation is what is called "backend".
+
+The `BackendServiceLoader` core service looks for a `BackendProviderService` implementation.
+Ours is defined in the class `ScalaBackendProviderService`.
+
+The implementing class also has to be registered as a "Java Service" in the `META-INF/services/io.cucumber.core.backend.BackendProviderService` file (in the `resources` folder).
+
+### Loading the glue
+
+When a Cucumber test starts, a Cucumber Runner starts and a `ScalaBackend` instance is created.
+The `ScalaBackend` instance will be used for running all the scenarios which are part of the test (defined by the _features path_ and the _glue path_).
+
+The first thing the Runner does is to "load the glue", that is find all the hooks and step definitions and register them.
+This is handled by the `ScalaBackend#loadGlue()` method.
+
+#### Scala implementation
+
+In the Cucumber Scala implementation, loading the glue code means:
+- finding all the **classes** inheriting `io.cucumber.scala.ScalaDsl` in the _glue path_, and for each:
+  - add it to the `Container` instance provided by Cucumber Core
+- finding all the **objects** singletons instances inheriting `io.cucumber.scala.ScalaDsl` in the _glue path_ and for each:
+  - extract the hooks and step definitions from it
+  - add the definitions to the `Glue` instance provided by Cucumber Core, as NOT `ScenarioScoped`
+
+Ideally all the glue code should be instantiated further (see next section), this is why we register classes (actually a list of `Class`) to the Container.
+But this cannot work for objects because they are by definitions singletons and already instantiated way before Cucumber.
+Thus, objects are not registered in the Container and their lifecycle is out of Cucumber scope.
+
+### Running a scenario
+
+For each scenario, the `buildWorld()` method of the backend is called.
+This is where the glue code should be initialized.
+
+#### Scala implementation
+
+For each **class** identified when loading the glue:
+- an instance is created by the `Lookup` provided by Cucumber Core
+- hooks and steps definitions are extracted from it
+- definitions are added to the `Glue` instance provided by Cucumber Core, as `ScenarioScoped`
+
+Being `ScenarioScoped` ensure instances are flushed at the end of the scenario and recreated for the next one.
+
+## Scala DSL
+
+The Scala DSL is made in a way that any class instance or object extending it contains what we call a **registry**:
+a list of the hooks and step definitions it contains.
+This is the purpose of `ScalaDslRegistry`.
+
+The registry is populated when the class instance or the object is created.
+Unlike other implementations there is no need to use annotations or reflection here.
+This is actually **similar to the Java8/Lambda implementation**.