Documentation.md

@@ -35,7 +35,7 @@ The following capabilities exist:
         GET http://localhost:8080/my-service/mymethod?simpleBoolean=true
         GET http://localhost:8080/my-service/mymethod?simpleString=a%20string%20with%20spaces
     
-*  __Complex types__ will be converted into JSON representation
+*  __Complex types__ (all others) will be converted into JSON representation
 
         GET http://localhost:8080/my-service/mymethod?complexParam={"number":23,"string":"hello"}
     
@@ -46,17 +46,24 @@ The following capabilities exist:
         GET http://localhost:8080/my-service/mymethod?parameterNull=%00
         
 *  __POST or GET__ is possible to make the call
+    * Url parameters are used for GET
+    * For POST, the parameters can be sent either as form data or as multipart 'text/plain' parts. Encoding is __always UTF-8__.
 
-*  __Big data transfers__ (e.g. file uploads and downloads) are supported by InputStream parameters and return types. 
-    * The HTTP return values are of type `application/octet-stream`
-    * The parameters must be specified as multipart message parts: `Content-Type: multipart/form-data; boundary=...` 
-       * Each parameter value is sent in a separate part: `Content-Disposition: form-data; name="...PARAMETER_NAME..." `
-       * InputStream parameters must use mime-type `application/octet-stream` 
-       * All other parameters go as `application/x-www-form-urlencoded; charset=UTF-8` 
+*  __Big data transfers__ (e.g. file uploads and downloads) are supported by handler InputStream parameters and return types.
+    * Stream HTTP return values are of type `application/octet-stream`.
+    * Stream parameters are only supported for POST multipart requests. Stream parts are of type `application/octet-stream`.
 
-* All parameters can be specified either as HTTP parameters or multipart message parts. Mixing is not possible.
+* You __can omit parameters in a request__. In this case, the default value of the parameter type is used. You can overwrite this behavior by setting your __own parameter default values__ with the `@DefaultValue` annotation in the handler code:
+    ```java
+    public void myMethod( @DefaultValue("defaultVal") String stringParam, @DefaultValue("23") int numParam)
+    ```
+  User specified default values will also be shown inside the generated documentation.
+  The type specific default values are:
+    * For numbers, the default value is __0__ (e.g. 0 for int or Integer, 0.0 for double and Double). Primitive and complex numbers are handled the same way.
+    * For booleans, the default value is __false__.
+    * For Strings, the default value is the __empty String ""__.
+    * For complex types, the default value is __null__.
 
-* You __cannot omit parameters in a request__ - all are needed by the server to find the request associated method. Simply set empty string and list values (e.g. parameter1=&parameter2=[ ]&parameterN=...).
 
 * If you have values of classes with an inheritance and you specify an interface or an upper class inside the method declaration, the default JSON conversion will fail because there is no dedicated type information inside the generated JSON Strings. For this case, you can annotate the parameter with `@Polymorph`. Doing this, we use [JSON-IO](https://github.com/jdereg/json-io) as serializer, that as of our knowledge is the only JSON serializer that is able to deal with class hierarchies at (de)serialization time. The specific types of the serialized objects will be added to the JSON containers if necessary.