diff --git a/lib/orogen/templates/tasks/Task.hpp b/lib/orogen/templates/tasks/Task.hpp index 2abb1552..1995ffb2 100644 --- a/lib/orogen/templates/tasks/Task.hpp +++ b/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 -