From 2ac2530c38ba7c78ebdc1dc7c0df1d2043b189eb Mon Sep 17 00:00:00 2001
From: konrad <konrad@kola-entertainments.de>
Date: Fri, 30 Nov 2018 23:59:58 +0100
Subject: [PATCH] improved docs

---
 Readme.md | 86 ++++++++++++++++++++++++++++++++++++-------------------
 1 file changed, 57 insertions(+), 29 deletions(-)

diff --git a/Readme.md b/Readme.md
index 5d6932f..e05cbdd 100644
--- a/Readme.md
+++ b/Readme.md
@@ -1,14 +1,40 @@
 # Vikunja Web Handler
 
-Vikunja was built with a maximum flexibility in mind while developing. To achive this, I built a set of easy-to-use
-functions and respective web handlers, all represented through interfaces.
+> When I started Vikunja, I started like everyone else, by writing a bunch of functions to do the logic and then a bunch of
+handler functions to parse the request data and call the implemented functions to do the logic and eventually return a dataset.
+After I implemented some functions, I've decided to save me a lot of hassle and put most of that "parse the request and call a 
+processing function"-logic to a general interface to facilitate development and not having to have a lot of similar code all over the place.
+
+This webhandler was built to be used in a REST-API, it takes and returns JSON, but can also be used in combination with own other handler
+implementations thus leading to much flexibility.
+
+## Features
+
+* Easy to use
+* Built for REST-APIs
+* Beautiful error handling built in
+* Manages rights
+* Pluggable authentication mechanisms
+
+### Table of contents
+
+* [CRUDable](#crudable)
+* [Rights](#rights)
+* [Handler Config](#handler-config)
+  * [Auth](#auth)
+  * [Logging](#logging)
+  * [Full Example](#full-example)
+* [Preprocessing](#preprocessing)
+  * [Pagination](#pagination)
+  * [Search](#search)
+* [Standard web handler](#standard-web-handler)
+* [Errors](#errors)
+
+In order to use the common web handler, the struct must implement the `web.CRUDable` and `web.Rights` interface.
 
 ## CRUDable
 
-This interface defines methods to Create/Read/ReadAll/Update/Delete something. In order to use the common web
-handler, the struct must implement this and the `Rights` interface.
-
-The interface is defined as followed:
+This interface defines methods to Create/Read/ReadAll/Update/Delete something. It is defined as followed:
 
 ```go
 type CRUDable interface {
@@ -36,7 +62,29 @@ All functions should behave like this, if they create or update something, they
 instance. The only exception is `ReadAll()` which returns an interface. Usually this is an array, because, well you cannot
 make an array of a set type (If you know a way to do this, don't hesitate to drop me a message).
 
-### Handler Config
+## Rights
+
+This interface defines methods to check for rights on structs. They accept an `Auth`-element as parameter and return a `bool`.
+
+The interface is defined as followed:
+
+```go
+type Rights interface {
+	IsAdmin(Auth) bool
+	CanWrite(Auth) bool
+	CanRead(Auth) bool
+	CanDelete(Auth) bool
+	CanUpdate(Auth) bool
+	CanCreate(Auth) bool
+}
+```
+
+When using the standard web handler, all methods except `CanRead()` are called before their `CRUD` counterparts. `CanRead()`
+is called after `ReadOne()` was invoked as this would otherwise mean getting an object from the db to check if the user has the
+right to see it and then getting it again if thats the case. Calling the function afterwards means we only have to get the
+object once.
+
+## Handler Config
 
 The handler has some options which you can (and need to) configure.
 
@@ -69,6 +117,8 @@ e.Use(func(next echo.HandlerFunc) echo.HandlerFunc {
 })
 ```
 
+## Preprocessing
+
 ### Pagination
 
 When using the `ReadAll`-method, the third parameter contains the requested page. Your function should return only the number of results
@@ -92,28 +142,6 @@ As the logic for "give me everything" and "give me everything where the name con
 the function like this, in order to keep the places with mostly the same logic as few as possible. Also just adding `?s=query` to the url one already 
 knows and uses is a lot more convenient.
 
-## Rights
-
-This interface defines methods to check for rights on structs. They accept an `Auth`-element as parameter and return a `bool`.
-
-The interface is defined as followed:
-
-```go
-type Rights interface {
-	IsAdmin(Auth) bool
-	CanWrite(Auth) bool
-	CanRead(Auth) bool
-	CanDelete(Auth) bool
-	CanUpdate(Auth) bool
-	CanCreate(Auth) bool
-}
-```
-
-When using the standard web handler, all methods except `CanRead()` are called before their `CRUD` counterparts. `CanRead()`
-is called after `ReadOne()` was invoked as this would otherwise mean getting an object from the db to check if the user has the
-right to see it and then getting it again if thats the case. Calling the function afterwards means we only have to get the
-object once. 
-
 ## Standard web handler
 
 You can define routes for the standard web handler like so: