fix indentation and line lenghts in Task.hpp's template

lib/orogen/templates/tasks/Task.hpp

@@ -6,98 +6,97 @@
 #include "<%= project.name.downcase %>/<%= task.basepath %><%= task.basename %>Base.hpp"
 
 <% task.full_namespace.split("::").each do |space| %>
-namespace <%= space %>{
+namespace <%= space %> {
 <% end %>
+    <%
+    doc = task.doc || "this task has no documentation, write one as a comment"\
+                        "block before the task_context statement in the orogen file"
 
-    /*! \class <%= task.basename %>
-     * \brief The task context provides and requires services. It uses an ExecutionEngine to perform its functions.
-     * Essential interfaces are operations, data flow ports and properties. These interfaces have been defined using the oroGen specification.
-     * In order to modify the interfaces you should (re)use oroGen and rely on the associated workflow.
-     * <%= task.doc %>
-     * \details
-     * The name of a TaskContext is primarily defined via:
-     \verbatim
-     deployment 'deployment_name'
-         task('custom_task_name','<%= "#{project.name}::#{task.basename}" %>')
-     end
-     \endverbatim
-     *  It can be dynamically adapted when the deployment is called with a prefix argument.
+    short_doc, *long_doc = doc.split("\n")
+    %>/*! \class <%= task.basename %>
+     * \brief <%= short_doc %><%= "\n     *" + long_doc.join("\n     * ") unless long_doc.empty? %>
      */
     class <%= task.basename %> : public <%= task.basename %>Base
     {
-	friend class <%= task.basename %>Base;
-    protected:
-
-<%= task.self_user_methods.sort_by(&:name).
-    map { |m| m.with_indent(8, :declaration) }.
-    compact.join("\n\n") %>
+        /** The base class is auto-generated by orogen to define the task's interface
+         *
+         * It is located in the .orogen/tasks folder
+         */
+        friend class <%= task.basename %>Base;
 
+    protected:
+<%= task.self_user_methods.sort_by(&:name)
+        .map { |m| m.with_indent(8, :declaration) }
+        .compact.join("\n\n") %>
     public:
         /** TaskContext constructor for <%= task.basename %>
-         * \param name Name of the task. This name needs to be unique to make it identifiable via nameservices.
-         * \param initial_state The initial TaskState of the TaskContext. Default is Stopped state.
+         * \param name Name of the task. This name needs to be unique to make
+         *             it identifiable via nameservices.
+         * \param initial_state The initial TaskState of the TaskContext.
+         *                      This is deprecated. It should always be the
+         *                      configure state.
          */
         <%= task.basename %>(std::string const& name = "<%= task.name %>"<%= ", TaskCore::TaskState initial_state = Stopped" unless task.fixed_initial_state? %>);
 
-        /** Default deconstructor of <%= task.basename %>
-         */
-	~<%= task.basename %>();
+        ~<%= task.basename %>();
 
-        /** This hook is called by Orocos when the state machine transitions
-         * from PreOperational to Stopped. If it returns false, then the
-         * component will stay in PreOperational. Otherwise, it goes into
+        /**
+         * Hook called when the state machine transitions from PreOperational to
          * Stopped.
          *
-         * It is meaningful only if the #needs_configuration has been specified
-         * in the task context definition with (for example):
-         \verbatim
-         task_context "TaskName" do
-           needs_configuration
-           ...
-         end
-         \endverbatim
+         * If the code throws an exception, the transition will be aborted
+         * and the component will end in the EXCEPTION state instead
+         *
+         * @return true if the transition can continue, false otherwise
          */
         bool configureHook();
 
-        /** This hook is called by Orocos when the state machine transitions
-         * from Stopped to Running. If it returns false, then the component will
-         * stay in Stopped. Otherwise, it goes into Running and updateHook()
-         * will be called.
+        /**
+         * Hook called when the state machine transition from Stopped to Running
+         *
+         * If the code throws an exception, the transition will be aborted
+         * and the component will end in the EXCEPTION state instead
+         *
+         * @return true if the transition is successful, false otherwise
          */
         bool startHook();
 
-        /** This hook is called by Orocos when the component is in the Running
-         * state, at each activity step. Here, the activity gives the "ticks"
-         * when the hook should be called.
+        /**
+         * Hook called on trigger in the Running state
+         *
+         * When this hook is exactly called depends on the chosen task's activity.
+         * For instance, if the task context is declared as periodic in the orogen
+         * specification, the task will be called at a fixed period.
+         *
+         * See Rock's documentation for a list of available triggering mechanisms
          *
          * The error(), exception() and fatal() calls, when called in this hook,
          * allow to get into the associated RunTimeError, Exception and
          * FatalError states.
-         *
-         * In the first case, updateHook() is still called, and recover() allows
-         * you to go back into the Running state.  In the second case, the
-         * errorHook() will be called instead of updateHook(). In Exception, the
-         * component is stopped and recover() needs to be called before starting
-         * it again. Finally, FatalError cannot be recovered.
          */
         void updateHook();
 
-        /** This hook is called by Orocos when the component is in the
-         * RunTimeError state, at each activity step. See the discussion in
-         * updateHook() about triggering options.
+        /**
+         * Hook called in the RuntimeError state, under the same conditions than
+         * the updateHook
          *
          * Call recover() to go back in the Runtime state.
          */
         void errorHook();
 
-        /** This hook is called by Orocos when the state machine transitions
-         * from Running to Stopped after stop() has been called.
+        /**
+         * Hook called when the component transitions out of the Running state
+         *
+         * This is called for any transition out of running, that is the
+         * transitions to Stopped, Exception and Fatal
          */
         void stopHook();
 
-        /** This hook is called by Orocos when the state machine transitions
-         * from Stopped to PreOperational, requiring the call to configureHook()
-         * before calling start() again.
+        /**
+         * Hook called on all transitions to PreOperational
+         *
+         * This is called for all transitions into PreOperational, that is
+         * either from Stopped or Exception
          */
         void cleanupHook();
     };
@@ -106,4 +105,3 @@ namespace <%= space %>{
 <% end %>
 
 #endif
-