[skip release] docs(readme): clarify and simplify the possible usages (…

…#16)

Signed-off-by: Gaël Jourdan-Weil <[email protected]>

README.md

@@ -14,7 +14,6 @@ While there is no official support by HERE, you may still raise issues via GitHu
 
 ## Prerequisites
 This plugin is compatible with:
-- Scala 2.12
 - sbt 1.3.0 or newer
 
 ## How to use it
@@ -27,6 +26,8 @@ Add the `sbt-bom` plugin to `plugins.sbt` file.
 addSbtPlugin("com.here.platform" % "sbt-bom" % "1.0.7")
 ```
 
+#### Add Maven central repository in your resolvers
+
 If you're encountering issues or using earlier versions, you might have to explicitly declare the Maven Central repository:
 ```scala
 resolvers += Resolver.url(
@@ -38,65 +39,98 @@ This will enable the project to access plugin files stored in Maven Central, htt
 
 ### Read & use a BOM
 
-#### In a `dependencyOverrides` context
+There are different ways to use the plugin depending on your use case.
+
+#### Use it in `dependencyOverrides`  (`Bom.dependencies`)
 
-If you want to get all the dependencies declared in the BOM and use their version to override yours, follow this step.
-If you're looking for more control, go to the [general context](#in-a-general-context) section below.
+If you want to get all the dependencies declared in the BOM and use their version to override yours.
 
-Add BOM dependency to the `build.sbt`:
+Use the following setup in your `build.sbt`:
 ```scala
 import com.here.bom.Bom
+
+// Declare the BOM
+// Note the usage of Bom.dependencies method
 lazy val jacksonDependencies = Bom.dependencies("com.fasterxml.jackson" % "jackson-bom" % "2.14.2")
+
+lazy val `demo` = project
+  .in(file("."))
+  // Load the BOM
+  .settings(jacksonDependencies)
+  // Add all dependencies of the BOM in dependencyOverrides
+  .settings(
+    dependencyOverrides ++= jacksonDependencies.key.value
+  )
 ```
 
-This creates an sbt `Setting` that resolves the list of `ModuleID` declared in a desired BOM.
+#### Use it in `dependencyOverrides` and `libraryDependencies` (`Bom.apply`)
 
-Enable this setting in the module configuration and use this setting in `dependencyOverrides`:
+If you want to:
+- get all the dependencies declared in the BOM and use their version to override yours,
+- also use the version of a BOM dependency explicitly
+
+Use the following setup in your `build.sbt`:
 ```scala
+import com.here.bom.Bom
+
+// Declare the BOM
+// Note the usage of Bom.apply method
+lazy val jacksonBom = Bom("com.fasterxml.jackson" % "jackson-bom" % "2.14.2")
+
 lazy val `demo` = project
   .in(file("."))
-  .settings(jacksonDependencies)
+  // Load the BOM
+  .settings(jacksonBom)
+  // Add some explicit dependencies
   .settings(
-    dependencyOverrides ++= jacksonDependencies.key.value
+    libraryDependencies += "com.fasterxml.jackson.core" % "jackson-core" % jacksonBom.key.value
+  )
+  // Add all dependencies of the BOM in dependencyOverrides
+  .settings(
+    dependencyOverrides ++= jacksonBom.key.value.bomDependencies
   )
 ```
 
-#### In a general context
+#### Custom usage (`Bom.read`)
 
-Add BOM dependency to the `build.sbt`:
+In addition to the common usages described above, you can also use the BOM in a custom way thanks to `Bom.read`.
+
+Example, in your `build.sbt`:
 ```scala
 import com.here.bom.Bom
-lazy val jacksonBom = Bom.read("com.fasterxml.jackson" % "jackson-bom" % "2.14.2")(bom => Dependencies(bom))
+
+// Declare the BOM and map it to a custom class
+// Note the usage of Bom.read method
+lazy val jacksonDependencies = Bom.read("com.fasterxml.jackson" % "jackson-bom" % "2.14.2")(bom => Dependencies(bom))
+
+lazy val `demo` = project
+  .in(file("."))
+  // Load the BOM
+  .settings(jacksonDependencies)
+  // Add some explicit dependencies
+  .settings(
+    libraryDependencies ++= jacksonDependencies.key.value.someDependencies
+  )
+  // Add all dependencies of the BOM in dependencyOverrides
+  .settings(
+    dependencyOverrides ++= jacksonDependencies.key.value.allDependencies
+  )
 ```
 
-This creates an sbt `Setting` that resolves a desired BOM, creates a `Bom` object from it and then builds a `Dependencies` object.
-Under the `project` directory, create a `Dependencies` class that takes a `Bom` as a constructor parameter.
-Inside this class, we can refer to the versions from the BOM.
-The class should expose a list of dependencies that used as `libraryDependencies`
+And in a `project/Dependencies.scala` file:
 ```scala
 import sbt._
 import com.here.bom.Bom
 
 case class Dependencies(bom: Bom) {
-  val dependencies: Seq[ModuleID] = Seq(
-    "com.fasterxml.jackson.core" % "jackson-databind" % bom
+  val someDependencies: Seq[ModuleID] = Seq(
+    "com.fasterxml.jackson.core" % "jackson-core" % bom
   )
 
-  // Note: you may also use bom.bomDependencies which gives you the list of all dependencies declared in the BOM.
-  // This gives the same result as Bom.dependencies (see above).
+  val allDependencies: Seq[ModuleID] = bom.bomDependencies
 }
 ```
 
-Enable this setting in the module configuration and use this setting in `libraryDependencies`:
-```scala
-lazy val `demo` = project
-  .in(file("."))
-  .settings(jacksonBom)
-  .settings(
-    libraryDependencies ++= jacksonBom.key.value.dependencies
-  )
-```
-
 ### Password-protected repositories
 The following text explains how to access password-protected repositories, specifically the HERE platform repository,
 using a file with credentials.