Added doxygen comments for generated proxies and stubs.

2 files changed, 95 insertions, 11 deletions

diff --git a/org.genivi.commonapi.core/src/org/genivi/commonapi/core/generator/FInterfaceProxyGenerator.xtend b/org.genivi.commonapi.core/src/org/genivi/commonapi/core/generator/FInterfaceProxyGenerator.xtend
index c218864..8bbb542 100644
--- a/org.genivi.commonapi.core/src/org/genivi/commonapi/core/generator/FInterfaceProxyGenerator.xtend
+++ b/org.genivi.commonapi.core/src/org/genivi/commonapi/core/generator/FInterfaceProxyGenerator.xtend
@@ -116,27 +116,70 @@ class FInterfaceProxyGenerator {
             ~«fInterface.proxyClassName»();
 
             «FOR attribute : fInterface.attributes»
+                /// Returns the wrapper class that provides access to the attribute «attribute.name».
                 virtual «attribute.generateGetMethodDefinition»;
             «ENDFOR»
 
             «FOR broadcast : fInterface.broadcasts»
+                /// Returns the wrapper class that provides access to the broadcast «broadcast.name».
                 virtual «broadcast.generateGetMethodDefinition»;
             «ENDFOR»
 
             «FOR method : fInterface.methods»
 
+                /**
+                 * Calls «method.name» with «IF method.isFireAndForget»Fire&Forget«ELSE»synchronous«ENDIF» semantics.
+                 * 
+«IF !method.inArgs.empty»     * All const parameters are input parameters to this method.«ENDIF»
+«IF !method.outArgs.empty»     * All non-const parameters will be filled with the returned values.«ENDIF»
+                 * The CallStatus will be filled when the method returns and indicate either
+                 * "SUCCESS" or which type of error has occurred. In case of an error, ONLY the CallStatus
+                 * will be set.
+                 «IF !method.isFireAndForget»
+                 * Synchronous calls are not supported (will block indefinitely) when mainloop integration is used.
+                 «ENDIF»
+                 */
                 virtual «method.generateDefinition»;
                 «IF !method.isFireAndForget»
+                    /**
+                     * Calls «method.name» with asynchronous semantics.
+                     * 
+                     * The provided callback will be called when the reply to this call arrives or
+                     * an error occurs during the call. The CallStatus will indicate either "SUCCESS"
+                     * or which type of error has occurred. In case of any error, ONLY the CallStatus
+                     * will have a defined value.
+                     * The std::future returned by this method will be fulfilled at arrival of the reply.
+                     * It will provide the same value for CallStatus as will be handed to the callback.
+                     */
                     virtual «method.generateAsyncDefinition»;
                 «ENDIF»
             «ENDFOR»
 
+            /// Returns the CommonAPI address of the remote partner this proxy communicates with.
             virtual std::string getAddress() const;
+
+            /// Returns the domain of the remote partner this proxy communicates with.
             virtual const std::string& getDomain() const;
+
+            /// Returns the service ID of the remote partner this proxy communicates with.
             virtual const std::string& getServiceId() const;
+
+            /// Returns the instance ID of the remote partner this proxy communicates with.
             virtual const std::string& getInstanceId() const;
+
+            /// Returns true if the remote partner for this proxy is available.
             virtual bool isAvailable() const;
+
+            /**
+             * Returns the wrapper class that is used to (de-)register for notifications about
+             * the availability of the remote partner of this proxy.
+             */
             virtual CommonAPI::ProxyStatusEvent& getProxyStatusEvent();
+
+            /**
+             * Returns the wrapper class that is used to access version information of the remote
+             * partner of this proxy.
+             */
             virtual CommonAPI::InterfaceVersionAttribute& getInterfaceVersionAttribute();
 
          private:
diff --git a/org.genivi.commonapi.core/src/org/genivi/commonapi/core/generator/FInterfaceStubGenerator.xtend b/org.genivi.commonapi.core/src/org/genivi/commonapi/core/generator/FInterfaceStubGenerator.xtend
index 9deb94f..a160cfc 100644
--- a/org.genivi.commonapi.core/src/org/genivi/commonapi/core/generator/FInterfaceStubGenerator.xtend
+++ b/org.genivi.commonapi.core/src/org/genivi/commonapi/core/generator/FInterfaceStubGenerator.xtend
@@ -32,45 +32,79 @@ class FInterfaceStubGenerator {
 
         «fInterface.model.generateNamespaceBeginDeclaration»
 
+        /**
+         * Receives messages from remote and handles all dispatching of deserialized calls
+         * to a stub for the service «fInterface.name». Also provides means to send broadcasts
+         * and attribute-changed-notifications of observable attributes as defined by this service.
+         * An application developer should not need to bother with this class.
+         */
         class «fInterface.stubAdapterClassName»: virtual public CommonAPI::StubAdapter, public «fInterface.name» {
          public:
             «FOR attribute : fInterface.attributes»
                 «IF attribute.isObservable»
+                    ///Notifies all remote listeners about a change of value of the attribute «attribute.name».
                     virtual void «attribute.stubAdapterClassFireChangedMethodName»(const «attribute.type.getNameReference(fInterface.model)»& «attribute.name») = 0;
                 «ENDIF»
             «ENDFOR»
 
             «FOR broadcast : fInterface.broadcasts»
+                /**
+                 * Sends a broadcast event for «broadcast.name». Should not be called directly.
+                 * Instead, the "fire<broadcastName>Event" methods of the stub should be used.
+                 */
                 virtual void «broadcast.stubAdapterClassFireEventMethodName»(«broadcast.outArgs.map['const ' + type.getNameReference(fInterface.model) + '& ' + name].join(', ')») = 0;
             «ENDFOR»        
         };
 
 
+        /**
+         * Defines the necessary callbacks to handle remote set events related to the attributes
+         * defined in the IDL description for «fInterface.name».
+         * For each attribute two callbacks are defined:
+         * - a verification callback that allows to verify the requested value and to prevent setting
+         *   e.g. an invalid value ("onRemoteSet<AttributeName>").
+         * - an action callback to do local work after the attribute value has been changed
+         *   ("onRemote<AttributeName>Changed").
+         *
+         * This class and the one below are the ones an application developer needs to have
+         * a look at if he wants to implement a service.
+         */
         class «fInterface.stubRemoteEventClassName» {
          public:
             virtual ~«fInterface.stubRemoteEventClassName»() { }
 
             «FOR attribute : fInterface.attributes»
+                /// Verification callback for remote set requests on the attribute «attribute.name».
                 virtual bool «attribute.stubRemoteEventClassSetMethodName»(«attribute.type.getNameReference(fInterface.model)» «attribute.name») = 0;
+                /// Action callback for remote set requests on the attribute «attribute.name».
                 virtual void «attribute.stubRemoteEventClassChangedMethodName»() = 0;
 
             «ENDFOR»
         };
 
 
+        /**
+         * Defines the interface that must be implemented by any class that should provide
+         * the service «fInterface.name» to remote clients.
+         * This class and the one above are the ones an application developer needs to have
+         * a look at if he wants to implement a service.
+         */
         class «fInterface.stubClassName» : public CommonAPI::Stub<«fInterface.stubAdapterClassName» , «fInterface.stubRemoteEventClassName»> {
          public:
             virtual ~«fInterface.stubClassName»() { }
 
             «FOR attribute : fInterface.attributes»
+                /// Provides getter access to the attribute «attribute.name».
                 virtual const «attribute.type.getNameReference(fInterface.model)»& «attribute.stubClassGetMethodName»() = 0;
             «ENDFOR»
 
             «FOR method: fInterface.methods»
+                /// This is the method that will be called on remote calls on the method «method.name».
                 virtual void «method.name»(«method.generateStubSignature») = 0;
             «ENDFOR»
             
             «FOR broadcast : fInterface.broadcasts»
+                /// Sends a broadcast event for «broadcast.name».
                 virtual void «broadcast.stubAdapterClassFireEventMethodName»(«broadcast.outArgs.map['const ' + type.getNameReference(fInterface.model) + '& ' + name].join(', ')») = 0;
             «ENDFOR»
         };
@@ -89,6 +123,16 @@ class FInterfaceStubGenerator {
 
         «fInterface.model.generateNamespaceBeginDeclaration»
 
+        /**
+         * Provides a default implementation for «fInterface.stubRemoteEventClassName» and
+         * «fInterface.stubClassName». Method callbacks have an empty implementation,
+         * remote set calls on attributes will always change the value of the attribute
+         * to the one received.
+         * 
+         * Override this stub if you only want to provide a subset of the functionality
+         * that would be defined for this service, and/or if you do not need any non-default
+         * behaviour.
+         */
         class «fInterface.stubDefaultClassName» : public «fInterface.stubClassName» {
          public:
             «fInterface.stubDefaultClassName»();
@@ -191,6 +235,14 @@ class FInterfaceStubGenerator {
                 return true;
             }
 
+            bool «fInterface.stubDefaultClassName»::RemoteEventHandler::«attribute.stubRemoteEventClassSetMethodName»(«attribute.type.getNameReference(fInterface.model)» value) {
+                return defaultStub_->«attribute.stubDefaultClassTrySetMethodName»(std::move(value));
+            }
+
+            void «fInterface.stubDefaultClassName»::RemoteEventHandler::«attribute.stubRemoteEventClassChangedMethodName»() {
+                defaultStub_->«attribute.stubRemoteEventClassChangedMethodName»();
+            }
+
         «ENDFOR»
 
         «FOR method : fInterface.methods»
@@ -210,17 +262,6 @@ class FInterfaceStubGenerator {
                 defaultStub_(defaultStub) {
         }
 
-        «FOR attribute : fInterface.attributes»
-            bool «fInterface.stubDefaultClassName»::RemoteEventHandler::«attribute.stubRemoteEventClassSetMethodName»(«attribute.type.getNameReference(fInterface.model)» value) {
-                return defaultStub_->«attribute.stubDefaultClassTrySetMethodName»(std::move(value));
-            }
-
-            void «fInterface.stubDefaultClassName»::RemoteEventHandler::«attribute.stubRemoteEventClassChangedMethodName»() {
-                defaultStub_->«attribute.stubRemoteEventClassChangedMethodName»();
-            }
-
-        «ENDFOR»
-
         «fInterface.model.generateNamespaceEndDeclaration»
     '''