Improve httpserver documentation (#2971)

Author: HHHartmann

docs/lua-modules/httpserver.md

@@ -36,20 +36,35 @@ Callback function has 2 arguments: `req` (request) and `res` (response). The fir
   object.
 - `method`: Request method that was used (e.g.`POST` or `GET`)
 - `url`: Requested URL
-- `onheader`: value to setup handler function for HTTP headers like `content-type`. Handler function has 3 parameters:
+- `onheader`: assign a function to this value which will be called as soon as HTTP headers like `content-type` are available.
+              This handler function has 3 parameters:
 
 	- `self`: `req` object
-	- `name`: Header name
+	- `name`: Header name. Will allways be lowercase.
 	- `value`: Header value
 
-- `ondata`: value to setup handler function HTTP data. Handler function has 2 parameters:
+- `ondata`: assign a function to this value which will be called as soon as body data is available. 
+            This handler function has 2 parameters:
 	- `self`: `req` object
-	- `chunk`: Request data
+	- `chunk`: Request data. If all data is received there will be one last call with data = nil
 
 The second object holds functions:
 
-- `send(self, data, [response_code])`: Function to send data to client. `self` is `req` object, `data` is data to send and `response_code` is HTTP response code like `200` or `404` (for example)
-- `send_header(self, header_name, header_data)`: Function to send HTTP headers to client. `self` is `req` object, `header_name` is HTTP header name and `header_data` is HTTP header data for client.
-- `finish([data])`: Function to finalize connection, optionally sending data. `data` is optional data to send on connection finalizing.
+- `send(self, data, [response_code])`: Function to send data to client. 
+  
+  - `self`: `res` object
+  - `data`: data to send (may be nil)
+  - `response_code`: the HTTP response code like `200`(default) or `404` (for example) *NOTE* if there are several calls with response_code given only the first one will be used. Any further codes given will be ignored.
+  
+- `send_header(self, header_name, header_data)`: Function to send HTTP headers to client. This function will not be available after data has been sent. (It will be nil.)
+
+  - `self`: `res` object
+  - `header_name`: the HTTP header name
+  - `header_data`: the HTTP header data
+
+- `finish([data[, response_code]])`: Function to finalize connection, optionally sending data and return code.
+
+  - `data`: optional data to send on connection finalizing
+  - `response_code`: the HTTP response code like `200`(default) or `404` (for example) *NOTE* if there are several calls with response_code given only the first one will be used. Any further codes given will be ignored.
 
 Full example can be found in [http-example.lua](../../lua_modules/http/http-example.lua)

lua_modules/http/httpserver.lua

@@ -116,7 +116,7 @@ do
         if not req or not req.ondata then return end
         req:ondata(chunk)
         -- NB: once length of seen chunks equals Content-Length:
-        --   onend(conn) is called
+        --   ondata(conn) is called
         body_len = body_len + #chunk
         -- print("-B", #chunk, body_len, cnt_len, node.heap())
         if body_len >= cnt_len then