From c1e2711ff891d17fb3a38a33f65d3ce1cd4cbb17 Mon Sep 17 00:00:00 2001
From: Steffen Vogel <stvogel@eonerc.rwth-aachen.de>
Date: Tue, 22 Sep 2015 15:27:23 +0200
Subject: [PATCH] improved documentation

---
 documentation/clients/File.md   |  2 +-
 documentation/clients/GTFPGA.md |  2 ++
 documentation/clients/NGSI.md   | 39 +++++++++++++++++++++++++++++++++
 documentation/clients/OPAL.md   | 10 +++++----
 documentation/clients/Socket.md | 10 +++++----
 server/include/ngsi.h           | 12 +++++++++-
 6 files changed, 65 insertions(+), 10 deletions(-)
 create mode 100644 documentation/clients/NGSI.md

diff --git a/documentation/clients/File.md b/documentation/clients/File.md
index d77c298cb..2551ec89c 100644
--- a/documentation/clients/File.md
+++ b/documentation/clients/File.md
@@ -4,7 +4,7 @@ The `file` node-type can be used to log or replay samples to / from disk.
 
 ## Configuration
 
-Every `file` node supports the following settings:
+Every `file` node supports the following special settings:
 
 #### `in` *(string: filesystem path)*
 
diff --git a/documentation/clients/GTFPGA.md b/documentation/clients/GTFPGA.md
index 015942eca..1a5db6722 100644
--- a/documentation/clients/GTFPGA.md
+++ b/documentation/clients/GTFPGA.md
@@ -10,6 +10,8 @@ The PowerPC core is used to forward values between RTDS and the S2SS server.
 
 ## Configuration
 
+Every `gtfpga` node support the following special settings:
+
 #### `slot`
 
 #### `id`
diff --git a/documentation/clients/NGSI.md b/documentation/clients/NGSI.md
new file mode 100644
index 000000000..a08d2f512
--- /dev/null
+++ b/documentation/clients/NGSI.md
@@ -0,0 +1,39 @@
+# OMA Next Generation Services Interface 10 {#ngsi}
+
+The `ngsi` node type implements an interface to FIWARE context brokers following the NGSI 10 RESTful HTTP API.
+
+This implementation if currently limited to the `updateContext` operation.
+Therefore only publishing updates is supported. Subscribtion or polling of events is planned for later versions.
+It's using `libcurl` and `libjansson` to communicate with the context broker over JSON.
+
+## Configuration
+
+Every `ngsi` node supports the following special settings:
+
+#### `endpoint` *(string: URL)*
+
+#### `ssl_verify` *(boolean)*
+
+#### `timeout` *(float: seconds)*
+
+#### `structure` *("flat" | "children")*
+
+  - `flat`:
+  - `children`:
+
+#### `mapping` *(array of strings)*
+
+Format for `structure = flat`: `"entityId(entityType).attributeName(attributeType)"`
+
+Format for `structure = children`: `"parentId(entityType).value(attributeType)"`
+
+### Example
+
+@todo add example from example.conf
+
+## Further reading
+
+This standard was specified by the Open Mobile Alliance (OMA).
+
+@see https://forge.fiware.org/plugins/mediawiki/wiki/fiware/index.php/FI-WARE_NGSI-10_Open_RESTful_API_Specification
+@see http://technical.openmobilealliance.org/Technical/Release_Program/docs/NGSI/V1_0-20120529-A/OMA-TS-NGSI_Context_Management-V1_0-20120529-A.pdf
\ No newline at end of file
diff --git a/documentation/clients/OPAL.md b/documentation/clients/OPAL.md
index 81bc4e68c..e115f38f5 100644
--- a/documentation/clients/OPAL.md
+++ b/documentation/clients/OPAL.md
@@ -1,4 +1,4 @@
-# OPAL-RT {#opal}
+# OPAL-RT Asynchronous Process {#opal}
 
 The communication between OPAL-RT models and the S2SS is established by using ansychronous programs.
 Asynchronous programs are are a feature of RT-LAB. They are used to exchange data between Simulink models and custom C programs.
@@ -7,11 +7,13 @@ For this purpose the C program handels IP/UDP communication via BSD sockets.
 
 ## Configuration
 
-`send_id`
+Every `opal` node supports the following special settings:
 
-`recv_id`
+#### `send_id` *(integer)*
 
-`reply`
+#### `recv_id` *(integer)*
+
+#### `reply` *(boolean)*
 
 ## Arguments for OPAL-RT block
 
diff --git a/documentation/clients/Socket.md b/documentation/clients/Socket.md
index 491242593..2748cb0e8 100644
--- a/documentation/clients/Socket.md
+++ b/documentation/clients/Socket.md
@@ -15,13 +15,15 @@ The implementation supports multiple protocols / OSI layers:
 
 ## Configuration
 
-#### `local`
+Every `socket` node supports the following special settings:
 
-#### `remote`
+#### `local` *("ip:port" | "mac:protocol")*
 
-#### `netem`
+#### `remote` *("ip:port" | "mac:protocol")*
 
-#### `layer`
+#### `netem` *(dictionary)*
+
+#### `layer` *("udp" | "ip" | "eth")*
 
 ### Example
 
diff --git a/server/include/ngsi.h b/server/include/ngsi.h
index f8d08a060..52e321bd3 100644
--- a/server/include/ngsi.h
+++ b/server/include/ngsi.h
@@ -33,22 +33,32 @@
 struct node;
 
 struct ngsi {
+	/** The NGSI context broker endpoint URL. */
 	const char *endpoint;
+	/** An optional authentication token which will be sent as HTTP header. */
 	const char *token;
 
+	/** HTTP timeout in seconds */
 	double timeout;
+	/** Boolean flag whether SSL server certificates should be verified or not. */ 
 	int ssl_verify;
 
+	/** Structure of published entitites */
 	enum ngsi_structure {
 		NGSI_FLAT,
 		NGSI_CHILDREN
 	} structure;
 	
-	struct curl_slist *headers;	
+	/** List of HTTP request headers for libcurl */
+	struct curl_slist *headers;
+	/** libcurl handle */
 	CURL *curl;
 
+	/** The complete JSON tree which will be used for contextUpdate requests */
 	json_t *context;
+	/** A mapping between indices of the S2SS messages and the attributes in ngsi::context */
 	json_t **context_map;
+	/** The number of mappings in ngsi::context_map */
 	int context_len;
 };