From e0bb713bb03c0aa79e69496c787c012a8e1b78d1 Mon Sep 17 00:00:00 2001
From: Thomas Gubler <thomasgubler@gmail.com>
Date: Thu, 4 Dec 2014 13:06:38 +0100
Subject: [PATCH] more documentation comments

---
 src/platforms/px4_middleware.h | 13 +++++++++++++
 src/platforms/px4_publisher.h  | 28 ++++++++++++++++++++++++----
 src/platforms/px4_subscriber.h | 32 +++++++++++++++++++++++++++++---
 3 files changed, 66 insertions(+), 7 deletions(-)

diff --git a/src/platforms/px4_middleware.h b/src/platforms/px4_middleware.h
index dece729070..c1465b4b1b 100644
--- a/src/platforms/px4_middleware.h
+++ b/src/platforms/px4_middleware.h
@@ -50,9 +50,15 @@ __EXPORT void init(int argc, char *argv[], const char *process_name);
 __EXPORT uint64_t get_time_micros();
 
 #if defined(__linux) || (defined(__APPLE__) && defined(__MACH__))
+/**
+ * Returns true if the app/task should continue to run
+ */
 bool ok() { return ros::ok(); }
 #else
 extern bool task_should_exit;
+/**
+ * Returns true if the app/task should continue to run
+ */
 bool ok() { return !task_should_exit; }
 #endif
 
@@ -60,8 +66,15 @@ class Rate
 {
 
 public:
+	/**
+	 * Construct the Rate object and set rate
+	 * @param rate_hz rate from which sleep time is calculated in Hz
+	 */
 	explicit Rate(unsigned rate_hz) { sleep_interval = 1e6 / rate_hz; }
 
+	/**
+	 * Sleep for 1/rate_hz s
+	 */
 	void sleep() { usleep(sleep_interval); }
 
 private:
diff --git a/src/platforms/px4_publisher.h b/src/platforms/px4_publisher.h
index 9ce211d250..b67421066a 100644
--- a/src/platforms/px4_publisher.h
+++ b/src/platforms/px4_publisher.h
@@ -52,33 +52,53 @@ namespace px4
 class Publisher
 {
 public:
+	/**
+	 * Construct Publisher by providing a ros::Publisher
+	 * @param ros_pub the ros publisher which will be used to perform the publications
+	 */
 	Publisher(ros::Publisher ros_pub) : _ros_pub(ros_pub)
 	{}
+
 	~Publisher() {};
+
+	/** Publishes msg
+	 * @param msg	    the message which is published to the topic
+	 */
 	template<typename M>
 	int publish(const M &msg) { _ros_pub.publish(msg); return 0; }
 private:
-	ros::Publisher _ros_pub;
+	ros::Publisher _ros_pub;	/**< Handle to the ros publisher */
 };
 #else
 class Publisher :
 	public uORB::PublicationNode
 {
 public:
+	/**
+	 * Construct Publisher by providing orb meta data
+	 * @param meta	    orb metadata for the topic which is used
+	 * @param list	    publisher is added to this list
+	 */
 	Publisher(const struct orb_metadata *meta,
 			List<uORB::PublicationNode *> * list) :
 		uORB::PublicationNode(meta, list)
 	{}
+
 	~Publisher() {};
+
+	/** Publishes msg
+	 * @param msg	    the message which is published to the topic
+	 */
 	template<typename M>
 	int publish(const M &msg) {
 		uORB::PublicationBase::update((void*)&msg);
 		return 0;
 	}
 
-	void update() {
-	//XXX list traversal callback, needed?
-	} ;
+	/**
+	 * Empty callback for list traversal
+	 */
+	void update() {} ;
 };
 #endif
 }
diff --git a/src/platforms/px4_subscriber.h b/src/platforms/px4_subscriber.h
index 6e0ef8aed6..fdd0367d59 100644
--- a/src/platforms/px4_subscriber.h
+++ b/src/platforms/px4_subscriber.h
@@ -54,15 +54,24 @@ namespace px4
 class Subscriber
 {
 public:
+	/**
+	 * Construct Subscriber by providing a ros::Subscriber
+	 * @param ros_sub the ros subscriber which will be used to perform the publications
+	 */
 	Subscriber(ros::Subscriber ros_sub) :
 		_ros_sub(ros_sub)
 	{}
+
 	~Subscriber() {};
 private:
-	ros::Subscriber _ros_sub;
+	ros::Subscriber _ros_sub;	/**< Handle to ros subscriber */
 };
+
 #else
-// typedef std::function<void(int)> CallbackFunction;
+
+/**
+ * Subscriber class which is used by nodehandle when building for NuttX
+ */
 class Subscriber
 {
 public:
@@ -71,12 +80,22 @@ public:
 private:
 };
 
+/**
+ * Subscriber class that is templated with the uorb subscription message type
+ */
 template<typename M>
 class SubscriberPX4 :
 	public Subscriber,
 	public uORB::Subscription<M>
 {
 public:
+	/**
+	 * Construct SubscriberPX4 by providing orb meta data
+	 * @param meta	    orb metadata for the topic which is used
+	 * @param callback	Callback, executed on receiving a new message
+	 * @param interval	Minimal interval between calls to callback
+	 * @param list	    subscriber is added to this list
+	 */
 	SubscriberPX4(const struct orb_metadata *meta,
 			unsigned interval,
 			std::function<void(const M&)> callback,
@@ -86,8 +105,14 @@ public:
 		_callback(callback)
 		//XXX store callback
 	{}
+
 	~SubscriberPX4() {};
 
+	/**
+	 * Update Subscription
+	 * Invoked by the list traversal in NodeHandle::spinOnce
+	 * If new data is available the callback is called
+	 */
 	void update() {
 		if (!uORB::Subscription<M>::updated()) {
 			/* Topic not updated, do not call callback */
@@ -102,7 +127,8 @@ public:
 
 	};
 private:
-	std::function<void(const M&)> _callback;
+	std::function<void(const M&)> _callback;	/**< Callback handle,
+							  called when new data is available */
 
 };
 #endif