Merge pull request #763 from jakecollins/fix-guice-docs

Update links and fix formatting in Cucumber Guice docs.

Author: aslakhellesoy

guice/README.md

@@ -1,5 +1,9 @@
 # Using Cucumber Guice
 
-The [package documentation](src/main/java/cucumber/api/guice/package.html) contains detailed instructions for using
-Cucumber Guice. In particular be sure to read the migration section if upgrading from earlier versions of Cucumber
-Guice.
+The package documentation contains detailed instructions for using Cucumber Guice. In particular be sure to read the 
+migration section if upgrading from earlier versions of Cucumber Guice.
+
+[Read package documentation online at cukes.info]
+(http://cukes.info/api/cucumber/jvm/javadoc/cucumber/api/guice/package-summary.html) 
+
+[Read package documentation offline (raw html)](src/main/java/cucumber/api/guice/package.html)

guice/src/main/java/cucumber/api/guice/CucumberModules.java

@@ -5,7 +5,7 @@
 
 /**
  * Provides a convenient <code>com.google.inject.Module</code> instance that contains bindings for
- * code>cucumber.runtime.java.guice.ScenarioScoped</code> annotation and for
+ * <code>cucumber.runtime.java.guice.ScenarioScoped</code> annotation and for
  * <code>cucumber.runtime.java.guice.ScenarioScope</code>.
  */
 public class CucumberModules {

guice/src/main/java/cucumber/api/guice/README.java

@@ -2,7 +2,7 @@
 
 
 /**
- * Please see documentation in package.html
+ * Please see package documentation in package.html
  */
 public class README {
 }

guice/src/main/java/cucumber/api/guice/package.html

@@ -3,116 +3,127 @@
     This module allows you to use Google Guice dependency injection in your Cucumber tests. Guice comes as standard with
     singleton scope and 'no scope'. This module adds Cucumber scenario scope to the scopes available for use in your
     test code. The rest of this documentation assumes you have at least a basic understanding of Guice. Please refer to
-    the Google documentation if necessary, see https://code.google.com/p/google-guice/wiki/Motivation?tm=6
-
-    <b>About scopes, injectors and migration from earlier versions</b>
-
+    the Guice wiki if necessary, see <a href="https://github.com/google/guice/wiki/Motivation"
+        target="_parent">
+    https://github.com/google/guice/wiki/Motivation</a>
+</p>
+    <h3>About scopes, injectors and migration from earlier versions</h3>
+<p>
     It's important to realise the differences in how this module functions when compared with earlier versions. The
     changes are as follows.
-
-    <= 1.1.7    A Guice injector is created at the start of each test scenario and is destroyed at the end of each test
-                scenario. There is no scenario scope, just singleton and 'no scope'.
-
-    > 1.1.7     A Guice injector is created once before any tests are run and is destroyed after the last test has run.
-                Before each test scenario a new scenario scope is created. At the end of the test scenario the scenario
-                scope is destroyed. Singleton scope exists throughout all test scenarios.
-
-    Users wishing to migrate to this version should replace <code>@Singleton</code> annotations with
-    <code>@ScenarioScope</code> annotations. Guice modules should also have their singleton bindings updated. All
-    bindings in <code>Scopes.SINGLETON</code> should be replaced with bindings in <code>CucumberScopes.SCENARIO</code>.
-
-    <b>Using the module</b>
-
+</p>
+    <h4>Version 1.1.7 and earlier</h4>
+<p>
+    A Guice injector is created at the start of each test scenario and is destroyed at the end of each test scenario.
+    There is no scenario scope, just singleton and 'no scope'.
+</p>
+    <h4>Version 1.1.8 onwards</h4>
+<p>
+    A Guice injector is created once before any tests are run and is destroyed after the last test has run. Before each
+    test scenario a new scenario scope is created. At the end of the test scenario the scenario scope is destroyed.
+    Singleton scope exists throughout all test scenarios.
+</p>
+    <h4>Migrating to version 1.1.8 or later</h4>
+<p>
+    Users wishing to migrate should replace <code>@Singleton</code> annotations with <code>@ScenarioScope</code>
+    annotations. Guice modules should also have their singleton bindings updated. All bindings in
+    <code>Scopes.SINGLETON</code> should be replaced with bindings in <code>CucumberScopes.SCENARIO</code>.
+</p>
+    <h3>Using the module</h3>
+<p>
     By including the <code>cucumber-guice</code> jar on your <code>CLASSPATH</code> your Step Definitions will be
     instantiated by Guice. There are two main modes of using the module: with scope annotations and with module
     bindings. The two modes can also be mixed. When mixing modes it is important to realise that binding a class in a
     scope in a module takes precedence if the same class is also bound using a scope annotation.
-
-    <b>Scoping your step definitions</b>
-
+</p>
+    <h3>Scoping your step definitions</h3>
+<p>
     Usually you will want to bind your step definition classes in either scenario scope or in singleton scope. It is not
     recommended to leave your step definition classes with no scope as it means that Cucumber will instantiate a new
     instance of the class for each step within a scenario that uses that step definition.
-
-    <b>Scenario scope</b>
-
+</p>
+    <h3>Scenario scope</h3>
+<p>
     Cucumber will create exactly one instance of a class bound in scenario scope for each scenario in which it is used.
     You should use scenario scope when you want to store state during a scenario but do not want the state to interfere
     with subsequent scenarios.
-
-    <b>Singleton scope</b>
-
+</p>
+<p>
+    <h3>Singleton scope</h3>
+<p>
     Cucumber will create just one instance of a class bound in singleton scope that will last for the lifetime of all
     test scenarios in the test run. You should use singleton scope if your classes are stateless. You can also use
     singleton scope when your classes contain state but with caution. You should be absolutely sure that a state change
     in one scenario could not possibly influence the success or failure of a subsequent scenario. As an example of when
     you might use a singleton, imagine you have an http client that is expensive to create. By holding a reference to
     the client in a class bound in singleton scope you can reuse the client in multiple scenarios.
-
-    <b>Using scope annotations</b>
-
+</p>
+    <h3>Using scope annotations</h3>
+<p>
     This is the easy route if you're new to Guice. To bind a class in scenario scope add the
     <code>cucumber.runtime.java.guice.ScenarioScoped</code> annotation to the class definition. The class should have
     a no-args constructor or one constructor that is annotated with <code>javax.inject.Inject</code>. For example:
-
-    <code>
+</p>
+    <pre>
         import cucumber.runtime.java.guice.ScenarioScoped;
         import javax.inject.Inject;
 
-        @ScenarioScoped
+        {@literal @}ScenarioScoped
         public class ScenarioScopedSteps {
 
             private final Object someInjectedDependency;
 
-            @Inject
+            {@literal @}Inject
             public ScenarioScopedSteps(Object someInjectedDependency) {
                 this.someInjectedDependency = someInjectedDependency;
             }
 
             ...
         }
-    </code>
-
+    </pre>
+<p>
     To bind a class in singleton scope add the <code>javax.inject.Singleton</code> annotation to the class definition.
     One strategy for using stateless step definitions is to use providers to share stateful scenario scoped instances
     between stateless singleton step definition instances. For example:
-
-    <code>
+</p>
+    <pre>
         import javax.inject.Inject;
         import javax.inject.Singleton;
 
-        @Singleton
+        {@literal @}Singleton
         public class MyStatelessSteps {
 
             private final Provider&lt;MyStatefulObject&gt; providerMyStatefulObject;
 
-            @Inject
+            {@literal @}Inject
             public MyStatelessSteps(Provider&lt;MyStatefulObject&gt; providerMyStatefulObject) {
                 this.providerMyStatefulObject = providerMyStatefulObject;
             }
 
-            @Given("^I have (\\d+) cukes in my belly$")
+            {@literal @}Given("^I have (\\d+) cukes in my belly$")
             public void I_have_cukes_in_my_belly(int n) {
                 providerMyStatefulObject.get().iHaveCukesInMyBelly(n);
             }
 
             ...
         }
-    </code>
-
-    See https://code.google.com/p/google-guice/wiki/InjectingProviders "Providers for Mixing Scopes"
-
-    <b>Using module bindings</b>
-
+    </pre>
+<p>
+    There is an alternative explanation of using
+    <a href="https://github.com/google/guice/wiki/InjectingProviders#providers-for-mixing-scopes" target="_parent">
+    providers for mixing scopes</a> on the Guice wiki.
+</p>
+    <h3>Using module bindings</h3>
+<p>
     As an alternative to using annotations you may prefer to declare Guice bindings in a class that implements
     <code>com.google.inject.Module</code>. To do this you should create a class that implements
     <code>cucumber.runtime.java.guice.InjectorSource</code>. This gives you complete control over how you obtain a
     Guice injector and it's Guice modules. The injector must provide a binding for
     <code>cucumber.runtime.java.guice.ScenarioScope</code>. It should also provide a binding for the
     <code>cucumber.runtime.java.guice.ScenarioScoped</code> annotation if your classes are using the annotation. The
     easiest way to do this it to use <code>CucumberModules.SCENARIO</code>. For example:
-
-    <code>
+</p>
+    <pre>
         import com.google.inject.Guice;
         import com.google.inject.Injector;
         import com.google.inject.Stage;
@@ -121,21 +132,19 @@
 
         public class YourInjectorSource implements InjectorSource {
 
-            @Override
+            {@literal @}Override
             public Injector getInjector() {
                 return Guice.createInjector(Stage.PRODUCTION, CucumberModules.SCENARIO, new YourModule());
             }
         }
-    </code>
-
+    </pre>
+<p>
     Cucumber needs to know where to find the <code>cucumber.runtime.java.guice.InjectorSource</code> that it will use.
     You should create a properties file called <code>cucumber-guice.properties</code> and place it in the root of the
     classpath. The file should contain a single property key called <code>guice.injector-source</code> with a value
     equal to the fully qualified name of the <code>cucumber.runtime.java.guice.InjectorSource</code>. For example:
-
-    <code>
-        guice.injector-source=com.company.YourInjectorSource
-    </code>
-
 </p>
+    <pre>
+        guice.injector-source=com.company.YourInjectorSource
+    </pre>
 </body>