Merge pull request #415 from dronecore/fix-comments

Public comments improvements

core/CMakeLists.txt

@@ -26,7 +26,6 @@ add_library(dronecore ${LIBRARY_TYPE}
     mavlink_commands.cpp
     mavlink_channels.cpp
     mavlink_receiver.cpp
-    plugin_base.cpp
     plugin_impl_base.cpp
     serial_connection.cpp
     tcp_connection.cpp

core/dronecore.h

@@ -28,9 +28,9 @@ class DroneCore {
     static constexpr int DEFAULT_UDP_PORT = 14540;
     /** @brief Default TCP remote IP (localhost). */
     static constexpr auto DEFAULT_TCP_REMOTE_IP = "127.0.0.1";
-    /**< @brief Default TCP remote port. */
+    /** @brief Default TCP remote port. */
     static constexpr int DEFAULT_TCP_REMOTE_PORT = 5760;
-    /**< @brief Default serial baudrate. */
+    /** @brief Default serial baudrate. */
     static constexpr int DEFAULT_SERIAL_BAUDRATE = 57600;
 
     /**
@@ -75,7 +75,7 @@ class DroneCore {
      * To accept only local connections of the machine, use 127.0.0.1.
      * For any incoming connections, use 0.0.0.0.
      *
-     * @param local_bind_ip The local UDP ip to listen to.
+     * @param local_ip The local UDP IP address to listen to.
      * @param local_port The local UDP port to listen to (defaults to 14540, the same as MAVROS).
      * @return The result of adding the connection.
      */

core/plugin_base.h

@@ -2,13 +2,29 @@
 
 namespace dronecore {
 
+/**
+ * @brief Base class for every plugin.
+ */
 class PluginBase {
 public:
-    PluginBase();
+    /**
+     * @brief Default Constructor.
+     */
+    PluginBase() = default;
+
+    /**
+     * @brief Default Destructor.
+     */
     virtual ~PluginBase() = default;
 
-    // Non-copyable
+    /**
+     * @brief Copy constructor (object is not copyable).
+     */
     PluginBase(const PluginBase &) = delete;
+
+    /**
+     * @brief Assign operator (object is not copyable).
+     */
     const PluginBase &operator=(const PluginBase &) = delete;
 };
 

core/system.h

@@ -18,12 +18,12 @@ class PluginImplBase;
  */
 class System {
 public:
-    /**
-     * @brief Constructor.
+    /** @private Constructor, used internally
      *
      * This constructor is not (and should not be) directly called by application code.
      *
-     * @param system_id %System id.
+     * @param parent `DroneCoreImpl` dependency.
+     * @param system_id System id.
      * @param comp_id Component id.
      */
     explicit System(DroneCoreImpl &parent, uint8_t system_id, uint8_t comp_id);
@@ -76,7 +76,6 @@ class System {
      */
     uint64_t get_uuid() const;
 
-    // Non-copyable
     /**
      * @brief Copy constructor (object is not copyable).
      */

generate_docs.sh

@@ -32,9 +32,20 @@ fi
 # Build and install locally.
 make INSTALL_PREFIX=$install_prefix default install
 
+return_result=0
 # Doxygen likes to run where the source is (because INPUT in .doxygen is empty),
 # so we cd there.
 pushd $install_prefix/include/dronecore
-doxygen $source_dir/.doxygen
+# If any warnings are thrown, we should not flag this as a success.
+doxygen_output_file=".doxygen_output.tmp"
+doxygen $source_dir/.doxygen &> $doxygen_output_file
+cat $doxygen_output_file
+if cat $doxygen_output_file | grep "warning" | grep -v "ignoring unsupported tag"
+then
+    return_result=1
+    echo "Please check doxygen warnings."
+fi
 $source_dir/generate_markdown_from_doxygen_xml.py $install_prefix/docs $install_prefix/docs
 popd
+
+exit $return_result

plugins/camera/camera.h

@@ -290,6 +290,9 @@ class Camera : public PluginBase {
      */
     struct VideoStreamInfo {
         VideoStreamSettings settings; /**< @brief Video stream settings. */
+        /**
+         * @brief Status type.
+         */
         enum class Status {
             NOT_RUNNING = 0, /**< @brief Video stream is not ongoing. */
             IN_PROGRESS /**< @brief Video stream in progress. */
@@ -348,7 +351,9 @@ class Camera : public PluginBase {
     struct Status {
         bool video_on; /**< @brief true if video capture is currently running. */
         bool photo_interval_on; /**< @brief true if video timelapse is currently active. */
-
+        /**
+         * @brief Storage status type.
+         */
         enum class StorageStatus {
             NOT_AVAILABLE, /**< @brief Storage status not available. */
             UNFORMATTED, /**< @brief Storage is not formatted (has no recognized file system). */

plugins/mission/mission_item.h

@@ -203,11 +203,11 @@ class MissionItem {
      */
     friend MissionImpl;
 
-    // Non-copyable
     /**
      * @brief Copy constructor (object is not copyable).
      */
     MissionItem(const MissionItem &) = delete;
+
     /**
      * @brief Equality operator (object is not copyable).
      */
@@ -218,8 +218,25 @@ class MissionItem {
     std::unique_ptr<MissionItemImpl> _impl;
 };
 
+/**
+ * @brief Equal operator to compare two `MissionItem` objects.
+ *
+ * @return `true` if items are equal.
+ */
 bool operator==(const MissionItem &lhs, const MissionItem &rhs);
+
+/**
+ * @brief Stream operator to print infos about a `MissionItem`.
+ *
+ * @return A reference to the stream.
+ */
 std::ostream &operator<<(std::ostream &str, MissionItem const &mission_item);
+
+/**
+ * @brief Stream operator to print infos about a `MissionItem::CameraAction`.
+ *
+ * @return A reference to the stream.
+ */
 std::ostream &operator<<(std::ostream &str, MissionItem::CameraAction const &camera_action);
 
 } // namespace dronecore

plugins/telemetry/telemetry.h

@@ -624,11 +624,11 @@ class Telemetry : public PluginBase {
      */
     void rc_status_async(rc_status_callback_t callback);
 
-    // Non-copyable
     /**
      * @brief Copy constructor (object is not copyable).
      */
     Telemetry(const Telemetry &) = delete;
+
     /**
      * @brief Equality operator (object is not copyable).
      */
@@ -639,28 +639,116 @@ class Telemetry : public PluginBase {
     std::unique_ptr<TelemetryImpl> _impl;
 };
 
+/**
+ * @brief Equal operator to compare two `Telemetry::Position` objects.
+ *
+ * @return `true` if items are equal.
+ */
 bool operator==(const Telemetry::Position &lhs, const Telemetry::Position &rhs);
+
+/**
+ * @brief Stream operator to print information about a `Telemetry::Position`.
+ *
+ * @return A reference to the stream.
+ */
 std::ostream &operator<<(std::ostream &str, Telemetry::Position const &position);
 
+/**
+ * @brief Equal operator to compare two `Telemetry::Health` objects.
+ *
+ * @return `true` if items are equal.
+ */
 bool operator==(const Telemetry::Health &lhs, const Telemetry::Health &rhs);
+
+/**
+ * @brief Stream operator to print information about a `Telemetry::Health`.
+ *
+ * @return A reference to the stream.
+ */
 std::ostream &operator<<(std::ostream &str, Telemetry::Health const &health);
 
+/**
+ * @brief Equal operator to compare two `Telemetry::GPSInfo` objects.
+ *
+ * @return `true` if items are equal.
+ */
 bool operator==(const Telemetry::GPSInfo &lhs, const Telemetry::GPSInfo &rhs);
+
+/**
+ * @brief Stream operator to print information about a `Telemetry::GPSInfo`.
+ *
+ * @return A reference to the stream.
+ */
 std::ostream &operator<<(std::ostream &str, Telemetry::GPSInfo const &gps_info);
 
+/**
+ * @brief Equal operator to compare two `Telemetry::Battery` objects.
+ *
+ * @return `true` if items are equal.
+ */
 bool operator==(const Telemetry::Battery &lhs, const Telemetry::Battery &rhs);
+
+/**
+ * @brief Stream operator to print information about a `Telemetry::Battery`.
+ *
+ * @return A reference to the stream.
+ */
 std::ostream &operator<<(std::ostream &str, Telemetry::Battery const &battery);
 
+/**
+ * @brief Equal operator to compare two `Telemetry::Quaternion` objects.
+ *
+ * @return `true` if items are equal.
+ */
 bool operator==(const Telemetry::Quaternion &lhs, const Telemetry::Quaternion &rhs);
+
+/**
+ * @brief Stream operator to print information about a `Telemetry::Quaternion`.
+ *
+ * @return A reference to the stream.
+ */
 std::ostream &operator<<(std::ostream &str, Telemetry::Quaternion const &quaternion);
 
+/**
+ * @brief Equal operator to compare two `Telemetry::EulerAngle` objects.
+ *
+ * @return `true` if items are equal.
+ */
 bool operator==(const Telemetry::EulerAngle &lhs, const Telemetry::EulerAngle &rhs);
+
+/**
+ * @brief Stream operator to print information about a `Telemetry::EulerAngle`.
+ *
+ * @return A reference to the stream.
+ */
 std::ostream &operator<<(std::ostream &str, Telemetry::EulerAngle const &euler_angle);
 
+/**
+ * @brief Equal operator to compare two `Telemetry::GroundSpeedNED` objects.
+ *
+ * @return `true` if items are equal.
+ */
 bool operator==(const Telemetry::GroundSpeedNED &lhs, const Telemetry::GroundSpeedNED &rhs);
+
+/**
+ * @brief Stream operator to print information about a `Telemetry::GroundSpeedNED`.
+ *
+ * @return A reference to the stream.
+ */
 std::ostream &operator<<(std::ostream &str, Telemetry::GroundSpeedNED const &ground_speed);
 
+/**
+ * @brief Equal operator to compare two `Telemetry::RCStatus` objects.
+ *
+ * @return `true` if items are equal.
+ */
 bool operator==(const Telemetry::RCStatus &lhs, const Telemetry::RCStatus &rhs);
+
+/**
+ * @brief Stream operator to print information about a `Telemetry::RCStatus`.
+ *
+ * @return A reference to the stream.
+ */
 std::ostream &operator<<(std::ostream &str, Telemetry::RCStatus const &rc_status);
 
 } // namespace dronecore