doc for system object IF improved

objectmanager/SystemObjectIF.h

@@ -1,26 +1,19 @@
-/**
+#ifndef FRAMEWORK_OBJECTMANAGER_SYSTEMOBJECTIF_H_
- * @file	SystemObjectIF.h
+#define FRAMEWORK_OBJECTMANAGER_SYSTEMOBJECTIF_H_
- * @brief	This file contains the definition of the SystemObjectIF interface.
- * @date	18.09.2012
- * @author	Bastian Baetz
- */
-
-#ifndef SYSTEMOBJECTIF_H_
-#define SYSTEMOBJECTIF_H_
 
 #include <framework/events/EventReportingProxyIF.h>
 #include <framework/returnvalues/HasReturnvaluesIF.h>
-#include <stdint.h>
+#include <cstdint>
 /**
- * \defgroup system_objects Software System Object Management
+ * @defgroup system_objects Software System Object Management
- * The classes to create System Objects and classes to manage these are contained in this group.
+ * The classes to create System Objects and classes to manage these are
- * System Objects are software elements that can be controlled externally. They all have a unique
+ * contained in this group. System Objects are software elements that can be
- * object identifier.
+ * controlled externally. They all have a unique object identifier.
  */
 
 /**
  * This is the typedef for object identifiers.
- * \ingroup system_objects
+ * @ingroup system_objects
  */
 typedef uint32_t object_id_t;
 
@@ -29,7 +22,8 @@ typedef uint32_t object_id_t;
  * list.
  * It does not provide any method definitions, still it is required to
  * perform a type check with dynamic_cast.
- * \ingroup system_objects
+ * @author  Bastian Baetz
+ * @ingroup system_objects
  */
 class SystemObjectIF : public EventReportingProxyIF {
 public:
@@ -41,24 +35,28 @@ public:
 	/**
 	 * The empty virtual destructor as required for C++ interfaces.
 	 */
-	virtual ~SystemObjectIF() {
+	virtual ~SystemObjectIF() {}
-	}
 	/**
-	 * Initializes all inter-object dependencies.
+	 * @brief   Initializes the object.
-	 * This is necessary to avoid circular dependencies of not-fully
+	 * There are initialization steps which can also be done in the constructor.
-	 * initialized objects on start up.
+	 * However, there is no clean way to get a returnvalue from a constructor.
-	 * @return	- \c RETURN_OK in case the initialization was successful
+	 * Furthermore some components require other system object to be created
-	 * 			- \c RETURN_FAILED otherwise
+	 * which might not have been built yet.
+	 * Therefore, a two-step initialization resolves this problem and prevents
+	 * circular dependencies of not-fully initialized objects on start up.
+	 * @return	- @c RETURN_OK in case the initialization was successful
+	 * 			- @c RETURN_FAILED otherwise
 	 */
 	virtual ReturnValue_t initialize() = 0;
 	/**
-	 * Checks, if all object-object interconnections are satisfying for operation.
+	 * @brief   Checks if all object-object interconnections are satisfying
-	 * Some objects need certain other objects (or a certain number), to be registered as children.
+	 *          for operation.
-	 * These checks can be done in this method.
+	 * Some objects need certain other objects (or a certain number), to be
-	 * @return	- \c RETURN_OK in case the check was successful
+	 * registered as children. These checks can be done in this method.
-	 * 			- \c any other code otherwise
+	 * @return	- @c RETURN_OK in case the check was successful
+	 * 			- @c any other code otherwise
 	 */
 	virtual ReturnValue_t checkObjectConnections() = 0;
 };
 
-#endif /* SYSTEMOBJECTIF_H_ */
+#endif /* FRAMEWORK_OBJECTMANAGER_SYSTEMOBJECTIF_H_ */