Extend documentation for unions and AttributeExtensions.

8 files changed, 340 insertions, 108 deletions

diff --git a/.gitignore b/.gitignore
index c83a012..70ac68b 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,3 +1,4 @@
+doc
 */bin
 */doc-gen
 */xtend-gen
diff --git a/CommonAPI-Examples/e02Attributes/README b/CommonAPI-Examples/e02Attributes/README
index 5f72951..758e4ff 100644
--- a/CommonAPI-Examples/e02Attributes/README
+++ b/CommonAPI-Examples/e02Attributes/README
@@ -63,20 +63,41 @@ If the implementation of the stub has to change the value of the attribute +x+,
 
 In the example the service increments a counter every 2 seconds and publishes the counter value via the interface attribute +x+.
 
-Now see the implementation of the client. The simplest case is to get the current value of +x+. The following extract is part of the main function:
+Now see the implementation of the client. The simplest case is to get the current value of +x+. The following extract shows one part of the main function:
 
 [source,{cppstr}]
 ----
-CommonAPI::CallStatus callStatus;
-int32_t value = 0;
-
-// Get actual attribute value from service
-myProxy->getXAttribute().getValue(callStatus, value);
-if (callStatus != CommonAPI::CallStatus::SUCCESS) {
-	std::cerr << "Remote call A failed!\n";
-	return -1;
+#include <iostream>
+
+#include <CommonAPI/CommonAPI.h>
+#include <commonapi/examples/E02AttributesProxy.h>
+
+using namespace commonapi::examples;
+
+int main() {
+
+	std::shared_ptr < CommonAPI::Runtime > runtime = CommonAPI::Runtime::load();
+
+	std::shared_ptr < CommonAPI::Factory > factory = runtime->createFactory();
+	const std::string& serviceAddress = 
+		"local:commonapi.examples.Attributes:commonapi.examples.Attributes";
+	std::shared_ptr < E02AttributesProxyDefault > myProxy =
+		factory->buildProxy < E02AttributesProxy > (serviceAddress);
+
+    while (!myProxy->isAvailable()) { usleep(10); }
+
+	CommonAPI::CallStatus callStatus;
+	int32_t value = 0;
+
+	// Get actual attribute value from service
+	myProxy->getXAttribute().getValue(callStatus, value);
+	if (callStatus != CommonAPI::CallStatus::SUCCESS) {
+		std::cerr << "Remote call A failed!\n";
+		return -1;
+	}
+	std::cout << "Got attribute value: " << value << std::endl;
+
 }
-std::cout << "Got attribute value: " << value << std::endl;
 ----
 
 The +getXAttribute+ method will deliver the type +XAttribute+ which has to be used for the access to +x+. Every access returns a flag named callStatus (please see the CommonAPI specification). Subscription requires in general the definition of a callback function which is called in case of an attribute change. The subscribe method of CommonAPI requires a function object; for a compact notation this function object can be defined as lambda function:
@@ -107,7 +128,7 @@ myProxy->getXAttribute().getChangedEvent().subscribe(
 	std::bind(recv_msg, std::placeholders::_1));
 ----
 
-Asynchronous setting of attributes via setValueAsync works analog as shown in the follwoing code extract where the more complex attribute _a1_ is set from the client:
+Asynchronous setting of attributes via setValueAsync works analog as shown in the following code extract where the more complex attribute _a1_ is set from the client:
 
 [source,{cppstr}]
 ----
@@ -131,3 +152,19 @@ std::function<void (const CommonAPI::CallStatus&, CommonTypes::a1Struct)> fcb_s
 myProxy->getA1Attribute().setValueAsync(valueStruct, fcb_s);
 ----
 
+As described above, in the chapter "Attribute Extensions" of this tutorial, it is possible to extend the standard CommonAPI for attributes by defining Attribute Extensions. In this example you have to:
+
+* include the template definition of the extension (AttributeCacheExtension.hpp)
+* to call a different factory method for creating the proxy (e.g. buildProxyWithDefaultAttributeExtension)
+* and then it is possible to call the new defined methods, e.g.
+
+[source,{cppstr}]
+----
+int32_t valueCached = 0;
+bool r;
+r = myProxy->getXAttributeExtension().getCachedValue(valueCached);
+std::cout << "Got cached attribute value[" << (int)r << "]: " << valueCached << std::endl;
+----
+
+See the source code of the example for a deeper insight.
+
diff --git a/CommonAPI-Examples/e06Unions/README b/CommonAPI-Examples/e06Unions/README
index d983df8..774f9b4 100644
--- a/CommonAPI-Examples/e06Unions/README
+++ b/CommonAPI-Examples/e06Unions/README
@@ -1,7 +1,7 @@
 Example 6: Unions
 ~~~~~~~~~~~~~~~~~
 
-Until now, some simple and complex data types in the examples already occurred. This example intends to describe the use of unions closer. Consider the following Franca IDL example:
+Until now, some simple and complex data types in the examples already occurred. This example intends to describe the use of unions closer and to compare it with the usage of polymorphic structs. Consider the following Franca IDL example:
 
 [source,java]
 ----
@@ -11,6 +11,7 @@ interface E06Unions {
 	version { major 1 minor 0 }
 
 	attribute CommonTypes.SettingsUnion u
+	attribute CommonTypes.SettingsStruct x
 }
 
 typeCollection CommonTypes {
@@ -29,10 +30,31 @@ typeCollection CommonTypes {
 		UInt8 channel
 		String name
 	}
+	
+	struct SettingsStruct polymorphic {
+    }
+    
+    struct SettingsStructMyTypedef extends SettingsStruct {
+    	MyTypedef id 
+    }
+    
+    struct SettingsStructMyEnum extends SettingsStruct {
+    	MyEnum status 
+    }
+    
+    struct SettingsStructUInt8 extends SettingsStruct {
+    	UInt8 channel 
+    }
+    
+    struct SettingsStructString extends SettingsStruct {
+    	String name 
+    }
 }
 ----
 
-We first want to leave the question aside whether this example makes sense from an application point of view or not; it is just an example for demonstration purposes. Union is a sort of polymorphic type; with unions we can transmit data of different types in one attribute. D-Bus knows a similar data type which is called variant. Variants are used in the D-Bus binding for the implementation of unions. The interesting point is here not the definition of the union, but the realization in CommonAPI. I just want to point out here that it can lead to problems with the compiler or generally to problems with your toolchain if you define unions with an significant number of members (eg. >10), because each of these members appears in the generated C++ code as template argument in the template declaration.
+We first want to leave the question aside whether this example makes sense from an application point of view or not; it is just an example for demonstration purposes. With unions we can transmit data of different types in one attribute. These different types are enumerated in one structure with the keyword *union*. D-Bus knows a similar data type which is called variant. Variants are used in the D-Bus binding for the implementation of unions. The interesting point is here not the definition of the union, but the realization in CommonAPI. I just want to point out here that it can lead to problems with the compiler or generally to problems with your toolchain if you define unions with an significant number of members (eg. >10), because each of these members appears in the generated C++ code as template argument in the template declaration.
+
+On the other hand we see the definition of a +polymorphic struct+ which can lead to a similar but not the same behavior. The difference is that the types of the +polymorphic struct+ definitions are extensions of a base type (here +SettingsStruct+), that means that they are inherited from this base type. The base type might contain some base elements which are then be inherited by the children. Another difference is, that the C++ API allows real polymorphic behavior. With Unions that is not possible, since there is no base type as we will see below. 
 
 The implementation of the set function for the attribute u in the stub implementation could be as follows:
 
@@ -48,53 +70,211 @@ void E06UnionsStubImpl::setMyValue(int n) {
 		std::string t3 = "abc";
 
 		if ( n == 0 ) {
-
 			CommonTypes::SettingsUnion v(t0);
 			setUAttribute(v);
+			setXAttribute(std::make_shared<CommonTypes::SettingsStructMyTypedef>(t0));
 		} else if ( n == 1 ) {
-
 			CommonTypes::SettingsUnion v(t1);
 			setUAttribute(v);
+			setXAttribute(std::make_shared<CommonTypes::SettingsStructMyEnum>(t1));
 		} else if ( n == 2 ) {
-
 			CommonTypes::SettingsUnion v(t2);
 			setUAttribute(v);
+			setXAttribute(std::make_shared<CommonTypes::SettingsStructUInt8>(t2));
 		} else if ( n == 3 ) {
-
 			CommonTypes::SettingsUnion v(t3);
 			setUAttribute(v);
+			setXAttribute(std::make_shared<CommonTypes::SettingsStructString>(t3));
 		}
 	}
 }
 ----
-Depending on a condition (here the value of n) the attribute u is filled with data of different types. The code on client side is:
+
+Depending on a condition (here the value of n) the attributes u and x are filled with data of different types. Please note that the argument of +setUAttribute+ has the type +CommonAPI::Variant<MyTypedef, MyEnum, uint8_t, std::string>+, whereas the argument of +setXAttribute+ is a pointer to the base type +SettingsStruct+.
+
+The standard implementation on client side to get the value of the attribute uses the API call +isType+ in case of the union attribute. First we have to subscribe; in the callback function it is possible to get the value of our attribute by checking the type which leads to an if / then / else cascade:
 
 [source,{cppstr}]
 ----
-myProxy->getUAttribute().getChangedEvent().
-		subscribe([&](const CommonTypes::SettingsUnion& v) {
+#include <iostream>
 
-	if ( v.isType<CommonTypes::MyTypedef>() ) {
+#include <CommonAPI/CommonAPI.h>
+#include <commonapi/examples/E06UnionsProxy.h>
+#include <commonapi/examples/CommonTypes.h>
+
+using namespace commonapi::examples;
 
-		std::cout << "Received MyTypedef with value " <<
-			v.get<CommonTypes::MyTypedef>() << std::endl;
+void evalA (const CommonTypes::SettingsUnion& v) {
 
+	if ( v.isType<CommonTypes::MyTypedef>() ) {
+		std::cout << "Received (A) MyTypedef with value " <<
+			v.get<CommonTypes::MyTypedef>() << " at index " <<
+			(int)v.getValueType() << std::endl;
 	} else if ( v.isType<CommonTypes::MyEnum>() ) {
+		std::cout << "Received (A) MyEnum with value " <<
+			(int) (v.get<CommonTypes::MyEnum>()) << " at index " <<
+			(int)v.getValueType() << std::endl;
+	} else if ( v.isType<uint8_t>() ) {
+		std::cout << "Received (A) uint8_t with value " <<
+			(int) (v.get<uint8_t>()) << " at index " <<
+			(int)v.getValueType() << std::endl;
+	} else if ( v.isType<std::string>() ) {
+		std::cout << "Received (A) string " << v.get<std::string>() <<
+			" at index " << (int)v.getValueType() << std::endl;
+	} else {
+		std::cout << "Received (A) change message with unknown type." << std::endl;
+	}
+}
 
-		std::cout << "Received MyEnum with value " <<
-			(int) (v.get<CommonTypes::MyEnum>()) << std::endl;
+void recv_msg(const CommonTypes::SettingsUnion& v) {
+	evalA(v);
+}
 
-	} else if ( v.isType<uint8_t>() ) {
+int main() {
+    std::shared_ptr<CommonAPI::Runtime> runtime = CommonAPI::Runtime::load();
+    std::shared_ptr<CommonAPI::Factory> factory = runtime->createFactory();
+    const std::string& serviceAddress =
+    	"local:commonapi.examples.Unions:commonapi.examples.Unions";
+    std::shared_ptr<E06UnionsProxyDefault> myProxy =
+    	factory->buildProxy<E06UnionsProxy> (serviceAddress);
+    while (!myProxy->isAvailable()) { usleep(10); }
 
-		std::cout << "Received uint8_t with value " <<
-			(int) (v.get<uint8_t>()) << std::endl;
+	std::function<void (CommonTypes::SettingsUnion)> f = recv_msg;
+	myProxy->getUAttribute().getChangedEvent().subscribe(f);
 
-	} else if ( v.isType<std::string>() ) {
+    while (true) { usleep(10); }
+    return 0;
+}
+----
+
+The example shows, how it is possible to detect the type and the value of the received attribute. However, the if / then / else cascade is not the only, perhaps not the best way to get the value of the union on client side footnote:[These two very good alternative implementations come from Martin Häfner from Harman. Thank you!]. One alternative implementation is based on an +typeIdOf+ function, which is at the moment not part of CommonAPI but can be additionally implemented (see +typeUtils.hpp+ of this example):
+
+[source,{cppstr}]
+----
+#include <type_traits>
+
+template <typename SearchT, typename... T>
+struct typeIdOf;
+
+template <typename SearchT, typename T>
+struct typeIdOf<SearchT, T> {
+
+	static const int value = std::is_same<SearchT, T>::value ? 1 : -1;
+};
+
+template <typename SearchT, typename T1, typename... T>
+struct typeIdOf<SearchT, T1, T...> {
+	static const int value = std::is_same<SearchT, T1>::value ? 
+		sizeof...(T)+1 : typeIdOf<SearchT, T...>::value;
+};
+----
+
+The evaluation method (corresponding to +evalA+ above) looks like:
+
+[source,{cppstr}]
+----
+template <typename T1, typename... T>
+void evalB (const CommonAPI::Variant<T1, T...>& v) {
+
+	switch (v.getValueType()) {
 
-		std::cout << "Received string with value " <<
-			v.get<std::string>() << std::endl;
+	case typeIdOf<CommonTypes::MyTypedef, T1, T...>::value:
+		std::cout << "Received (B) MyTypedef with value " <<
+			(int)(v.template get<CommonTypes::MyTypedef>()) << std::endl;
+		break;
+	case typeIdOf<CommonTypes::MyEnum, T1, T...>::value:
+		std::cout << "Received (B) MyEnum with value " <<
+			(int)(v.template get<CommonTypes::MyEnum>()) << std::endl;
+		break;
+	case typeIdOf<uint8_t, T1, T...>::value:
+		std::cout << "Received (B) uint8_t with value " <<
+			(int)(v.template get<uint8_t>()) << std::endl;
+		break;
+	case typeIdOf<std::string, T1, T...>::value:
+		std::cout << "Received (B) string " <<
+			v.template get<std::string>() << std::endl;
+		break;
+	default:
+		std::cout << "Received (B) change message with unknown type." << std::endl;
+		break;
 	}
-});
+}
 ----
 
-The example shows, how it is possible to detect the type and the value of the received attribute.
+One advantage here is that instead of the if / then / else statement a switch / case statement can be used. 
+
+The second alternative implementation uses the function overloading. The overloaded functions are defined within a structure (+MyVisitor+ in the example) that is used as a visitor in the evaluation function:
+
+[source,{cppstr}]
+----
+struct MyVisitor {
+
+	explicit inline MyVisitor() {}
+
+	template<typename... T>
+	inline void eval(const CommonAPI::Variant<T...>& v) {
+		CommonAPI::ApplyVoidVisitor<MyVisitor,
+				CommonAPI::Variant<T...>, T...>::visit(*this, v);
+	}
+
+	void operator()(CommonTypes::MyTypedef val) {
+		std::cout << "Received (C) MyTypedef with value " << (int)val << std::endl;
+	}
+
+	void operator()(CommonTypes::MyEnum val) {
+		std::cout << "Received (C) MyEnum with value " << (int)val << std::endl;
+	}
+
+	void operator()(uint8_t val) {
+		std::cout << "Received (C) uint8_t with value " << (int)val << std::endl;
+	}
+
+	void operator()(std::string val) {
+		std::cout << "Received (C) string " << val << std::endl;
+	}
+
+	template<typename T>
+	void operator()(const T&) {
+		std::cout << "Received (C) change message with unknown type." << std::endl;
+	}
+
+	void operator()() {
+		std::cout << "NOOP." << std::endl;
+	}
+};
+
+void evalC(const CommonTypes::SettingsUnion& v) {
+	MyVisitor visitor;
+	visitor.eval(v);
+}
+----
+
+Finally, it should given here for comparison the implementation on the client side for the +polymorphic struct+. The subscription for a message receive function is identical to the previous implementation; the message receive function now looks as follows:
+
+[source,{cppstr}]
+----
+void recv_msg(std::shared_ptr<CommonTypes::SettingsStruct> x) {
+
+	if ( std::shared_ptr<CommonTypes::SettingsStructMyTypedef> sp =
+		std::dynamic_pointer_cast<CommonTypes::SettingsStructMyTypedef>(x) ) {
+		std::cout << "Received (D) MyTypedef with value " <<
+			(int)sp->id << std::endl;
+	} else if ( std::shared_ptr<CommonTypes::SettingsStructMyEnum> sp =
+		std::dynamic_pointer_cast<CommonTypes::SettingsStructMyEnum>(x) ) {
+		std::cout << "Received (D) MyEnum with value " <<
+			(int)sp->status << std::endl;
+	} else if ( std::shared_ptr<CommonTypes::SettingsStructUInt8> sp =
+		std::dynamic_pointer_cast<CommonTypes::SettingsStructUInt8>(x) ) {
+		std::cout << "Received (D) uint8_t with value " <<
+			(int)sp->channel << std::endl;
+	} else if ( std::shared_ptr<CommonTypes::SettingsStructString> sp =
+		std::dynamic_pointer_cast<CommonTypes::SettingsStructString>(x) ) {
+		std::cout << "Received (D) string " << sp->name << std::endl;
+	} else {
+		std::cout << "Received (D) change message with unknown type." << std::endl;
+	}
+}
+----
+
+The result you get now by dynamic cast of the base type.
+
diff --git a/README b/README
index b121be1..76053ad 100644
--- a/README
+++ b/README
@@ -1,76 +1,68 @@
-GENIVI_CommonAPI-D-Bus
-======================
+IPC CommonAPI C++ Tools
+-----------------------
 :Author: Juergen Gehring - juergen.gehring@bmw.de, Manfred Bathelt - manfred.bathelt@bmw.de
-:doctitle: GENIVI_CommonAPI-D-Bus
+:doctitle: IPC CommonAPI C++ Tools
+:version:
 
 Copyright
----------
-Copyright (C) 2013, GENIVI Alliance, Inc.
-Copyright (C) 2013, BMW AG
-
-This file is part of GENIVI Project IPC Common API.
- 
-Contributions are licensed to the GENIVI Alliance under one or more
-Contribution License Agreements or MPL 2.0 .
- 
-(C) Copyright
-This Source Code Form is subject to the terms of the
-Mozilla Public License, v. 2.0. If a  copy of the MPL was not distributed with
-this file, You can obtain one at http://mozilla.org/MPL/2.0/.
++++++++++
+Copyright (C) 2014, BMW AG.
+Copyright (C) 2014, GENIVI Alliance, Inc.
+This file is part of GENIVI Project IPC Common API C++ Tools.
  
-For further information see https://collab.genivi.org/wiki/display/genivi/SysInfraEGCommonIDLCommonAPIGuide
+Contributions are licensed to the GENIVI Alliance under one or more Contribution License Agreements or MPL 2.0.
 
-== License
-This project is licensed under MPL 2.0
+License
++++++++ 
+This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0. If a copy of the MPL was not distributed with this file, you can obtain one at http://mozilla.org/MPL/2.0/.
 
-Contribution is done under GENIVI CLA or MPL2.0. 
+Version
++++++++
+{version}
 
-== Version
-The current version can be taken from the git.
+Further information
++++++++++++++++++++
+Source code and latest news can be found at http://projects.genivi.org/commonapi/.
 
-== Common API Overview
+Common API Overview
+~~~~~~~~~~~~~~~~~~~
 
-Common API and its mechanism specific bindings (e.g. Common API D-Bus) provide a set of libraries and tools to work with 
-RPC communication in a way independent of wich mechanism is used. It consist currently consists of four subprojects:
-----
-CommonAPI - This is the base C++ library, which provides the application interface for users and can 
-            load runtime bindings such as dbus. 
-CommonAPI-Tools - The eclipse based tools for CommonAPI. This is essentially the code generator for 
-                  Franca -> Common API C++ code.
-                  (This is the current package.) 
-CommonAPI-D-Bus - This is the D-Bus binding C++ library, which provides the necesary code to communicate 
-                  over D-Bus. This is invisible to the application code, and simply needs to be linked against.
-CommonAPI-D-Bus-Tools - The eclipse based tools for CommonAPI D-Bus. This is the code generator for 
-                        Franca -> Common API D-Bus C++ code.
-----
-== Usage Instructions
+Common API C++ and its mechanism specific bindings (e.g. Common API D-Bus) provide a set of libraries and tools to work with 
+RPC communication in a way independent of which mechanism is used. It currently consists of four sub-projects:
 
-The simplest way to use the CommonAPI Tools is to add the update site available on the GENIVI project servers to you Eclipse. 
-This is available under:
+*CommonAPI* - This is the base C++ library, which provides the application interface for users and can load runtime bindings such as DBus.
+ 
+*CommonAPI-Tools* - The Eclipse based tools for CommonAPI. This is essentially the code generator for the generation of C++ code from Franca IDL. 
+
+*CommonAPI-D-Bus* - This is the D-Bus binding C++ library, which provides the necessary code to communicate over D-Bus. This is invisible to the application code, and simply needs to be linked against. 
+
+*CommonAPI-D-Bus-Tools* - The eclipse based tools for CommonAPI D-Bus. This is the code generator for Franca IDL to Common API D-Bus C++ code.
+
+Usage Instructions
+~~~~~~~~~~~~~~~~~~
+
+The simplest way to use the CommonAPI Tools is to add the update site available on the GENIVI project servers to your Eclipse. This is available under:
 
 Help->Install New Software->Add Button
 
 Enter the following URL: http://docs.projects.genivi.org/yamaica-update-site/CommonAPI/updatesite/ and confirm. 
 
-This provides CommonAPI, CommonAPI-D-Bus and all dependencies. 
+This provides CommonAPI, CommonAPI-D-Bus and all dependencies.
 
-Then select the newly added site in the site selection dropdown box, and in the Software selection window, 
-select the entire "GENIVI Common API" Tree.   
+Then select the newly added site in the site selection dropdown box, and in the Software selection window, select the entire "GENIVI Common API" Tree.
 
-After the software has been installed in Eclipse you can right-click on any .fidl file and generate C++ code for CommonAPI D-Bus 
-by selecting the "CommonAPI->Generate Common API Code" option.
+After the software has been installed in Eclipse you can right-click on any .fidl file and generate C++ code for CommonAPI by selecting the "CommonAPI->Generate Common API Code" option.
 
-== Build Instructions
+Build Instructions
+~~~~~~~~~~~~~~~~~~
 
 These are Eclipse Plug-In projects which require Xtext2 and Franca as dependencies within Eclipse. 
 
 An automated build process via Maven for the update-site and the command line interface are provided.
-As a first step to build the update-site, make sure that everything is configured correctly, i.e. the dependencies between CommonAPI-D-Bus and CommonAPI
-itself are set correctly.
-If you don't want to build the CommonAPI-D-Bus-Tools components, you have to adjust the update-site category.xml and the "modules" section in the pom.xml
-of the org.genivi.commonapi.parent.releng accordingly. 
 
-To build change into the org.genivi.commonapi.parent.releng directory and run 
+As a first step to build the update-site, make sure that everything is configured correctly, i.e. the dependencies between CommonAPI-D-Bus and CommonAPI itself are set correctly. If you don't want to build the CommonAPI-D-Bus-Tools components, you have to adjust the update-site category.xml and the "modules" section in the pom.xml of the org.genivi.commonapi.parent.releng accordingly. 
+
+To build change into the org.genivi.commonapi.parent.releng directory and run:
 
 ----
 mvn tycho-versions:set-version -DnewVersion=<version-you-want-to-set>-SNAPSHOT
@@ -84,7 +76,8 @@ Next, to build the updatesite, adjust your category.xml in the org.genivi.common
 mvn clean verify
 ----
 
-in the org.genivi.commonapi.parent.releng directory. Now every project will be built and the update site will be created in org.genivi.commonapi.updatesite/target/repository/
+in the org.genivi.commonapi.parent.releng directory. Now every project will be built and the update site will be created in org.genivi.commonapi.updatesite/target/repository/.
+
 If no configuration files are changed, the features
 
 ----
@@ -95,9 +88,10 @@ org.genivi.commonapi.dbus
 
 will be included in the updatesite.
 
-The command line interface will be built for different platforms, with zip-files as generated output. These zip-files can be found in org.genivi.commonapi.cli.product/target/products/
+The command line interface will be built for different platforms, with zip-files as generated output. These zip-files can be found in org.genivi.commonapi.cli.product/target/products/.
 
 A osgi based application will be contained in the zip-files. This application should be called as:
+
 ----
 commonapi_generator [options] file [file...]
                             Valid Options are:
@@ -107,26 +101,37 @@ commonapi_generator [options] file [file...]
                             on each generated file (for example your license)
 ----
 
-== Working on the code & contribution
+Working on the code & contribution
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.First get the code from the git:
-        git clone 
+- First get the code from the git:
+----
+git clone
+---- 
 
-.Get an overview of all branches:
-        git branch
+- Get an overview of all branches:
+----
+git branch
+----
 
-.Switch to the branch you want to work on (master is the feature branch) and verify that it has switched (* changed)
-        git checkout <your branch>
-        git branch
+- Switch to the branch you want to work on (master is the feature branch) and verify that it has switched (* changed)
+----
+git checkout <your branch>
+git branch
+----
 
-.Best practice is to create a local branch based on the current branch:
-        git branch working_branch
+- Best practice is to create a local branch based on the current branch:
+----
+git branch working_branch
+----
 
 Start working, best practice is to commit smaller, compilable pieces during the development process that makes it easier to handle later on.
 
-.If you want to commit you changes, send them to the author, you can create a patch like this:
-        git format-patch working_branch <your branch>
+- If you want to commit you changes, send them to the author, you can create a patch like this:
+----
+git format-patch working_branch <your branch>
+----
 
-This creates a set of patches that are published via the mailing list.The patches will be discussed and then merged & uploaded on the git by the maintainer.
+This creates a set of patches that are published via the mailing list. The patches will be discussed and then merged & uploaded on the git by the maintainer.
 
-Patches can be accepted either under GENIVI Cla or MPL 2.0 (see section License). Please be sure that the signed-off-by is set correctly. For more, check out http://gerrit.googlecode.com/svn/documentation/2.0/user-signedoffby.html
+Patches can be accepted under MPL 2.0 (see section License). Please be sure that the signed-off-by is set correctly. For more, check out http://gerrit.googlecode.com/svn/documentation/2.0/user-signedoffby.html
diff --git a/docx/CommonAPISpecification b/docx/CommonAPISpecification
index d6056d6..bf02176 100644
--- a/docx/CommonAPISpecification
+++ b/docx/CommonAPISpecification
@@ -4,17 +4,17 @@
 :imagedir:
 :cppstr: c++
 
-CommonAPI C++ Specification          
+CommonAPI C++ Specification
 ===========================
 
 This is the specification for *Common API {version}* released at {revdate}.
 
 .Copyright and License
 *******************************************************************************
-Copyright (C) 2013, GENIVI Alliance, Inc.
-Copyright (C) 2013, BMW AG
+Copyright (C) 2014, BMW AG
+Copyright (C) 2014, GENIVI Alliance, Inc.
 
-This file is part of the GENIVI IPC Common API C++i project.
+This file is part of the GENIVI IPC Common API C++ project.
 
 Contributions are licensed to the GENIVI Alliance under one or more
 Contribution License Agreements or MPL 2.0.
diff --git a/docx/Makefile b/docx/Makefile
index 3e5a42a..4e146aa 100644
--- a/docx/Makefile
+++ b/docx/Makefile
@@ -10,7 +10,15 @@ commonapi_version=$(PROJECT_VERSION)
 
 all: doc
 
-doc: spec_html spec_pdf tut_html tut_pdf test_html test_pdf
+doc: readme_html spec_html spec_pdf tut_html tut_pdf test_html test_pdf
+
+readme_html: docgendir
+	mkdir -p $(htmldocgendir)
+	asciidoc \
+		-a version=$(commonapi_version) \
+		-a tabsize=4 \
+		-o $(htmldocgendir)/readme.html \
+		../README
 
 spec_html: docgendir
 	mkdir -p $(htmldocgendir)
diff --git a/docx/Tutorial b/docx/Tutorial
index 73d7587..742a6b6 100644
--- a/docx/Tutorial
+++ b/docx/Tutorial
@@ -31,7 +31,7 @@ CommonAPI is a GENIVI project. Source code and latest news can be found at http:
 
 For documentation please visit the GENIVI document page http://docs.projects.genivi.org/.
 
-CommonAPI currently consists of four subprojects:
+CommonAPI currently consists of four sub-projects:
 
 [width="80%",cols="3,10"]
 |=========================================================
@@ -56,7 +56,7 @@ Before we proceed you should clarifiy whether you are a user, in the sense that
 
 Requirements
 ~~~~~~~~~~~~
-- Code generator and Franca tooling are based on Eclipse. Please make sure that you have an appropriate Eclipse version installed (see the compatibility table at the beginning of the document or the README file).
+- Code generator and Franca tooling are based on Eclipse. Please make sure that you have an appropriate Eclipse version installed.
 - Make sure all requirements to build the CommonAPI Runtime are installed and in the correct version. CommonAPI was developed using gcc 4.6 and gcc 4.7, but is feature compatible to gcc 4.5 and compiler compatible to gcc 4.4.
 
 Set up your environment as CommonAPI user
@@ -122,7 +122,7 @@ Download, patch and install version 1.4.16 of libdbus (*WARNING*: _Not_ followin
 $ wget http://dbus.freedesktop.org/releases/dbus/dbus-1.4.16.tar.gz
 $ tar -xzf dbus-1.4.16.tar.gz
 $ cd dbus-1.4.16
-$ patch -p1 < </your/download/path>/common-api-dbus-runtime/dbus-DBusMessage-add-support-for-custom-marshaling.patch
+$ patch -p1 < </your/commonapi/path>/common-api-dbus-runtime/dbus-DBusMessage-add-support-for-custom-marshaling.patch
 $ ./configure --prefix=/usr/local
 $ make -C dbus
 $ sudo make -C dbus install
@@ -586,7 +586,7 @@ As described in the CommonAPI specification there is a general scheme to include
 - Generate the proxy for your interface with the API method +buildProxyWithDefaultAttributeExtension+ if you want a common extension. For the specific extension call build proxy with the attribute extension as template parameter.
 - Now you can call the implemented functions of your extension via a +getNameAttributeExtension()+ call (where +Name+ is the name of your attribute).
 
-Example of an extension class for caching attributes (file +AttributeCacheExtension.hpp+):
+Example of an extension class for caching attributes (file +AttributeCacheExtension.hpp+, see example e02Attributes):
 [source,{cppstr}]
 ----
 #include <CommonAPI/CommonAPI.h>
diff --git a/docx/index.html b/docx/index.html
index 8eb743e..a233241 100644
--- a/docx/index.html
+++ b/docx/index.html
@@ -19,5 +19,6 @@
 <TR><TD>Tutorial and examples for IPC Common API C++ usage</TD><TD><a href="html/Tutorial.html">Tutorial (HTML)</a></TD><TD><a href="pdf/Tutorial.pdf">Tutorial (PDF)</a></TD></TR>
 <TR><TD>IPC Common API C++ Specification</TD><TD><a href="html/CommonAPISpecification.html">Specification (HTML)</a></TD><TD><a href="pdf/CommonAPISpecification.pdf">Specification (PDF)</a></TD></TR>
 <TR><TD>Regression Test Documentation</TD><TD><a href="html/tests/index.html">Test Documentation (HTML)</a></TD><TD><a href="pdf/tests/CommonAPITests.pdf">Test Documentation (PDF)</a></TD></TR>
+<TR><TD>README CommonAPI C++ Tools</TD><TD><a href="html/readme.html">README (HTML)</a></TD><TD><a href=""></a></TD></TR>
 </TABLE>
 </body></html>