Updated the Weighting documentation to reflect the current state of G…

…H. (#1141)

docs/core/weighting.md

@@ -1,39 +1,46 @@
 ## Weighting
 
-In order to create a custom Weighting you need to do the following:
+A weighting allows to create a "weight" for an edge. The weight of an edge reflects the cost of travelling along this edge. 
+All implementations of [RoutingAlgorithm](https://github.com/graphhopper/graphhopper/blob/master/core/src/main/java/com/graphhopper/routing/RoutingAlgorithm.java)
+in GraphHopper calculate the shortest path, which means the path with the [lowest overall cost from A to B](https://en.wikipedia.org/wiki/Shortest_path_problem). 
+The definition of the cost function is up to you, so you can create a cost function (we call this weighting) for the fastest path. 
+GraphHopper will still calculate the path with the lowest cost, but you can define the cost as a mix of distance speed, as shown in the [FastestWeighting](https://github.com/graphhopper/graphhopper/blob/master/core/src/main/java/com/graphhopper/routing/weighting/FastestWeighting.java).
 
- 1. implement the Weighting class
- 2. create a subclass of GraphHopper and overwrite createWeighting where you return a new instance of your custom weighting if e.g. the string 'customweighting' is specified. Otherwise let the super class handle it.
+In order to create a custom weighting you need to do the following:
 
-See AvoidEdgesWeighting for an example of a weighting which avoids certain edges (i.e. returns infinity weight). 
-If your blocking edges change per-request you need to disable the speed mode e.g. via `ch.disable=true` as URL or Java hints parameter.
+ 1. Implement the Weighting class
+ 2. Create a subclass of GraphHopper and overwrite `createWeighting`
 
-Now you need to create your custom GraphHopper:
+### Implement your own weighting
+
+A simple weighting is the [ShortestWeighting](https://github.com/graphhopper/graphhopper/blob/master/core/src/main/java/com/graphhopper/routing/weighting/ShortestWeighting.java),
+it calculates the shortest path. You could go from there and create your own weighting.
+
+If you only want to change small parts of an existing weighting, it might be a good idea to extend the [AbstractAdjustedWeighting](https://github.com/graphhopper/graphhopper/blob/master/core/src/main/java/com/graphhopper/routing/weighting/AbstractAdjustedWeighting.java),
+a sample can be found in the [AvoidEdgesWeighting](https://github.com/graphhopper/graphhopper/blob/master/core/src/main/java/com/graphhopper/routing/weighting/AvoidEdgesWeighting.java).
+If your weights change on a per-request base, like the [BlockAreaWeighting](https://github.com/graphhopper/graphhopper/blob/bbd62fded97be060fc09177f9fae794cea284554/core/src/main/java/com/graphhopper/routing/weighting/BlockAreaWeighting.java),
+you cannot use the 'speed mode', but have to use the 'hybrid mode' or 'flexible mode' (more details [here](https://github.com/graphhopper/graphhopper#technical-overview)).
+If you haven't disabled the 'speed mode' in your config, you have to disable it for the requests by appending `ch.disable=true`
+in the request url.
+
+### Extend GraphHopper
+
+For general information on how to extend GraphHopper have a look [here](low-level-api.md).
+
+Extending GraphHopper is easy, just need to override the `createWeighting` method of the GraphHopper class. 
+We return a new instance of our custom weighting if the string `my_custom_weighting` is given. Otherwise let the super class handle it:
 
 ```java
 class MyGraphHopper extends GraphHopper {
 
-    Set<Integer> forbiddenEdges;
-    public void determineForbiddenEdges() {
-       forbiddenEdges = ...
-    }
-
     @Override
-    public Weighting createWeighting( WeightingMap wMap, FlagEncoder encoder )
-    {
-        String weighting = wMap.getWeighting();
-        if ("BLOCKING".equalsIgnoreCase(weighting)) 
-        {
-            AvoidEdgesWeighting w = new AvoidEdgesWeighting(encoder);
-            w.addEdges(forbiddenEdges);
-            return w;
-        } else 
-        {
-            return super.createWeighting(weighting, encoder);
+    public Weighting createWeighting(HintsMap hintsMap, FlagEncoder encoder, Graph graph) {
+        String weightingStr = hintsMap.getWeighting().toLowerCase();
+        if ("my_custom_weighting".equals(weighting)) {
+            return new MyCustomWeighting(encoder);
+        } else {
+            return super.createWeighting(hintsMap, encoder, graph);
         }
     }
 }
-```
-
-For `forbiddenEdges` you need to determine the edges from some GPS coordinates. 
-Have a look into the [location index docs](./location-index.md). 
+```