Adding docs check

ci/check_format.sh

@@ -1,8 +1,12 @@
 #!/bin/bash
+set -euo pipefail
 
 # Perform code format (cmake target)
 cmake --build "$1" --target clangformat
 
+# Check for missing public API docs (non-zero exit fails CI)
+python3 scripts/check_public_docs.py
+
 # Display diff
 git --no-pager diff
 

include/depthai/basalt/BasaltVIO.hpp

@@ -23,6 +23,7 @@ namespace node {
 class BasaltVIO : public NodeCRTP<ThreadedHostNode, BasaltVIO> {
    public:
     constexpr static const char* NAME = "BasaltVIO";
+    /// Create a Basalt VIO node.
     BasaltVIO();
     ~BasaltVIO();
 
@@ -59,12 +60,15 @@ class BasaltVIO : public NodeCRTP<ThreadedHostNode, BasaltVIO> {
      * VIO configuration file.
      */
     basalt::VioConfig vioConfig;
+    /// Set IMU update rate in Hz.
     void setImuUpdateRate(int rate) {
         imuUpdateRate = rate;
     }
+    /// Set path to the VIO configuration file.
     void setConfigPath(const std::string& path) {
         configPath = path;
     }
+    /// Use spec translation for camera-to-IMU extrinsics if available.
     void setUseSpecTranslation(bool use) {
         useSpecTranslation = use;
     }

include/depthai/common/ImgTransformations.hpp

@@ -152,6 +152,10 @@ struct ImgTransformation {
      */
     float getVFov(bool source = false) const;
 
+    /**
+     * Retrieve currently set source crop rectangles.
+     * @return Vector of source crops
+     */
     std::vector<dai::RotatedRect> getSrcCrops() const;
 
     /**
@@ -204,11 +208,37 @@ struct ImgTransformation {
      * @param scaleY Scale factor in the vertical direction
      */
     ImgTransformation& addScale(float scaleX, float scaleY);
+    /**
+     * Append source crop rectangles.
+     * @param crops Vector of source crops to add
+     */
     ImgTransformation& addSrcCrops(const std::vector<dai::RotatedRect>& crops);
+    /**
+     * Set output image size.
+     * @param width Output width
+     * @param height Output height
+     */
     ImgTransformation& setSize(size_t width, size_t height);
+    /**
+     * Set input image size.
+     * @param width Input width
+     * @param height Input height
+     */
     ImgTransformation& setSourceSize(size_t width, size_t height);
+    /**
+     * Set source intrinsic matrix.
+     * @param intrinsicMatrix 3x3 intrinsic matrix
+     */
     ImgTransformation& setIntrinsicMatrix(std::array<std::array<float, 3>, 3> intrinsicMatrix);
+    /**
+     * Set the source distortion model.
+     * @param model Distortion model
+     */
     ImgTransformation& setDistortionModel(CameraModel model);
+    /**
+     * Set the source distortion coefficients.
+     * @param coefficients Distortion coefficients
+     */
     ImgTransformation& setDistortionCoefficients(std::vector<float> coefficients);
 
     /**

include/depthai/common/Keypoint.hpp

@@ -19,16 +19,26 @@ struct Keypoint {
     std::string labelName = "";
 
     Keypoint() = default;
+    /**
+     * Construct a keypoint from 3D image coordinates.
+     * @throws std::invalid_argument if confidence is negative.
+     */
     explicit Keypoint(Point3f imageCoordinates, float conf = 0.f, uint32_t label = 0, std::string labelName = "")
         : imageCoordinates(imageCoordinates), confidence(conf), label(label), labelName(labelName) {
         if(confidence < 0.f) {
             throw std::invalid_argument("Confidence must be non-negative.");
         }
     }
 
+    /**
+     * Construct a keypoint from 2D image coordinates (z = 0).
+     */
     explicit Keypoint(Point2f imageCoordinates, float confidence = 0.f, uint32_t label = 0, std::string labelName = "")
         : Keypoint(Point3f{imageCoordinates.x, imageCoordinates.y, 0.f}, confidence, label, labelName) {}
 
+    /**
+     * Construct a keypoint from explicit x/y/z coordinates.
+     */
     explicit Keypoint(float x, float y, float z, float confidence = 0.f, uint32_t label = 0, std::string labelName = "")
         : Keypoint(Point3f{x, y, z}, confidence, label, labelName) {}
 

include/depthai/common/KeypointsListT.hpp

@@ -18,9 +18,16 @@ struct KeypointsListT {
 
    public:
     KeypointsListT() = default;
+    /**
+     * Construct with keypoints and edges.
+     * @throws std::runtime_error if any edge index is out of range.
+     */
     explicit KeypointsListT(std::vector<KeypointT> keypoints, std::vector<Edge> edges) : keypoints(std::move(keypoints)), edges(std::move(edges)) {
         validateEdges();
     }
+    /**
+     * Construct with keypoints only (no edges).
+     */
     explicit KeypointsListT(std::vector<KeypointT> keypoints) : keypoints(std::move(keypoints)) {}
     ~KeypointsListT() = default;
 
@@ -32,28 +39,52 @@ struct KeypointsListT {
     using iterator = typename std::vector<KeypointT>::iterator;
     using const_iterator = typename std::vector<KeypointT>::const_iterator;
 
+    /**
+     * Iterator to the first keypoint.
+     */
     iterator begin() noexcept {
         return keypoints.begin();
     }
+    /**
+     * Iterator to one-past-the-last keypoint.
+     */
     iterator end() noexcept {
         return keypoints.end();
     }
 
+    /**
+     * Const iterator to the first keypoint.
+     */
     const_iterator begin() const noexcept {
         return keypoints.begin();
     }
+    /**
+     * Const iterator to one-past-the-last keypoint.
+     */
     const_iterator end() const noexcept {
         return keypoints.end();
     }
+    /**
+     * Const iterator to the first keypoint.
+     */
     const_iterator cbegin() const noexcept {
         return keypoints.cbegin();
     }
+    /**
+     * Const iterator to one-past-the-last keypoint.
+     */
     const_iterator cend() const noexcept {
         return keypoints.cend();
     }
+    /**
+     * Return true if the list is empty.
+     */
     bool empty() const noexcept {
         return keypoints.empty();
     }
+    /**
+     * Return the number of keypoints.
+     */
     size_t size() const noexcept {
         return keypoints.size();
     }

include/depthai/common/Point2f.hpp

@@ -15,11 +15,17 @@ namespace dai {
  */
 struct Point2f {
     Point2f() = default;
+    /**
+     * Construct a 2D point with explicit coordinates.
+     */
     Point2f(float x, float y) {
         this->x = x;
         this->y = y;
         this->hasNormalized = false;
     }
+    /**
+     * Construct a 2D point and explicitly mark normalization.
+     */
     Point2f(float x, float y, bool normalized) {
         this->x = x;
         this->y = y;
@@ -30,6 +36,9 @@ struct Point2f {
     bool normalized = false;
     bool hasNormalized = false;
 
+    /**
+     * Return whether the point is normalized to [0,1].
+     */
     bool isNormalized() const {
         if(hasNormalized) {
             return normalized;

include/depthai/common/Point3d.hpp

@@ -15,6 +15,9 @@ namespace dai {
  */
 struct Point3d {
     Point3d() = default;
+    /**
+     * Construct a 3D point from coordinates.
+     */
     Point3d(double x, double y, double z) : x(x), y(y), z(z) {}
     double x = 0, y = 0, z = 0;
 };

include/depthai/common/Point3f.hpp

@@ -15,6 +15,9 @@ namespace dai {
  */
 struct Point3f {
     Point3f() = default;
+    /**
+     * Construct a 3D point from coordinates.
+     */
     Point3f(float x, float y, float z) : x(x), y(y), z(z) {}
     float x = 0, y = 0, z = 0;
 };

include/depthai/common/Quaterniond.hpp

@@ -15,6 +15,9 @@ namespace dai {
  */
 struct Quaterniond {
     Quaterniond() = default;
+    /**
+     * Construct a quaternion from components.
+     */
     Quaterniond(double qx, double qy, double qz, double qw) : qx(qx), qy(qy), qz(qz), qw(qw) {}
     double qx = 0, qy = 0, qz = 0, qw = 1;
 };

include/depthai/common/Rect.hpp

@@ -18,15 +18,36 @@ namespace dai {
 struct Rect {
     // default constructor
     Rect() = default;
+    /**
+     * Construct a rectangle from top-left and size.
+     */
     Rect(float x, float y, float width, float height) : x(x), y(y), width(width), height(height) {}
+    /**
+     * Construct a rectangle and explicitly mark normalization.
+     */
     Rect(float x, float y, float width, float height, bool normalized)
         : x(x), y(y), width(width), height(height), normalized(normalized), hasNormalized(true) {}
+    /**
+     * Copy-construct a rectangle.
+     */
     Rect(const Rect& r) : x(r.x), y(r.y), width(r.width), height(r.height), normalized(r.normalized), hasNormalized(r.hasNormalized) {}
+    /**
+     * Construct a rectangle from origin point and size.
+     */
     Rect(const Point2f& org, const Size2f& sz) : x(org.x), y(org.y), width(sz.width), height(sz.height) {}
+    /**
+     * Construct a rectangle from origin point and size and explicit normalization.
+     */
     Rect(const Point2f& org, const Size2f& sz, bool normalized)
         : x(org.x), y(org.y), width(sz.width), height(sz.height), normalized(normalized), hasNormalized(true) {}
+    /**
+     * Construct a rectangle from two corner points.
+     */
     Rect(const Point2f& pt1, const Point2f& pt2)
         : x(std::min(pt1.x, pt2.x)), y(std::min(pt1.y, pt2.y)), width(std::max(pt1.x, pt2.x) - x), height(std::max(pt1.y, pt2.y) - y) {}
+    /**
+     * Construct a rectangle from two corner points with explicit normalization.
+     */
     Rect(const Point2f& pt1, const Point2f& pt2, bool normalized)
         : x(std::min(pt1.x, pt2.x)),
           y(std::min(pt1.y, pt2.y)),

include/depthai/common/RotatedRect.hpp

@@ -19,21 +19,34 @@ struct RotatedRect {
     float angle = 0.f;
 
     RotatedRect() = default;
+    /**
+     * Construct a rotated rectangle from center/size and angle.
+     * @throws std::runtime_error if center and size normalization do not match.
+     */
     RotatedRect(const Point2f& center, const Size2f& size, float angle) : center(center), size(size), angle(angle) {
         if(size.isNormalized() != center.isNormalized()) {
             throw std::runtime_error("Cannot create RotatedRect with mixed normalization");
         }
     }
+    /**
+     * Construct a rotated rectangle from an axis-aligned rectangle and angle.
+     */
     RotatedRect(const Rect& rect, float angle = 0.f)
         : center(rect.x + rect.width / 2.0f, rect.y + rect.height / 2.0f, rect.isNormalized()),
           size(rect.width, rect.height, rect.isNormalized()),
           angle(angle) {}
 
+    /**
+     * Convert to the outer axis-aligned rectangle.
+     */
     operator Rect() const {
         const auto [minx, miny, maxx, maxy] = getOuterRect();
         return Rect(minx, miny, maxx - minx, maxy - miny);
     }
 
+    /**
+     * Return whether coordinates are normalized to [0,1].
+     */
     bool isNormalized() const {
         if(size.isNormalized() != center.isNormalized()) {
             throw std::runtime_error("Cannot denormalize RotatedRect with mixed normalization");

include/depthai/device/BoardConfig.hpp

@@ -68,10 +68,15 @@ struct BoardConfig {
         Drive drive = MA_2;
         bool schmitt = false, slewFast = false;
         GPIO() = default;
+        /// Construct GPIO config with direction only.
         GPIO(Direction direction) : direction(direction) {}
+        /// Construct GPIO config with direction and level.
         GPIO(Direction direction, Level level) : direction(direction), level(level) {}
+        /// Construct GPIO config with direction, level, and pull.
         GPIO(Direction direction, Level level, Pull pull) : direction(direction), level(level), pull(pull) {}
+        /// Construct GPIO config with direction and mode.
         GPIO(Direction direction, Mode mode) : mode(mode), direction(direction) {}
+        /// Construct GPIO config with direction, mode, and pull.
         GPIO(Direction direction, Mode mode, Pull pull) : mode(mode), direction(direction), pull(pull) {}
     };
     std::unordered_map<std::int8_t, GPIO> gpio;
@@ -138,6 +143,7 @@ struct BoardConfig {
     std::unordered_map<CameraBoardSocket, Camera> camera;
 
     struct IMU {
+        /// Construct IMU config with default pin assignments.
         IMU() : bus(0), interrupt(53), wake(34), csGpio(8), boot(46), reset(45) {}
         int8_t bus, interrupt, wake, csGpio, boot, reset;
     };
@@ -149,7 +155,9 @@ struct BoardConfig {
         uint16_t width, height;
         ImgFrame::Type frameType;
         bool enable;
+        /// Construct UVC config with resolution; NV12 and enabled by default.
         UVC(uint16_t width, uint16_t height) : width(width), height(height), frameType(ImgFrame::Type::NV12), enable(true) {}
+        /// Construct UVC config with default 1920x1080 resolution.
         UVC() : UVC(1920, 1080) {}
     };
     std::optional<UVC> uvc;

include/depthai/device/CalibrationHandler.hpp

@@ -638,6 +638,7 @@ class CalibrationHandler {
         static constexpr bool value = false;
     };
     template <typename... T>
+    /// RTABMap support required to access this API.
     void getRTABMapCameraModel(T...) {
         static_assert(dependent_false<T...>::value, "Library not configured with RTABMap support");
     }

include/depthai/device/CallbackHandler.hpp

@@ -18,6 +18,7 @@ class CallbackHandler {
 
    public:
     void setCallback(std::function<std::shared_ptr<ADatatype>(std::shared_ptr<ADatatype>)> cb);
+    /// Create a handler for a stream with a processing callback.
     CallbackHandler(std::shared_ptr<XLinkConnection> conn,
                     const std::string& streamName,
                     std::function<std::shared_ptr<ADatatype>(std::shared_ptr<ADatatype>)> cb);

include/depthai/device/CrashDump.hpp

@@ -73,6 +73,7 @@ struct CrashDump {
     std::string depthaiCommitHash;
     std::string deviceId;
 
+    /// Serialize crash dump to JSON.
     nlohmann::json serializeToJson() const {
         std::vector<std::uint8_t> data;
         utility::serialize<SerializationType::JSON>(*this, data);

include/depthai/device/DeviceBootloader.hpp

@@ -179,6 +179,7 @@ class DeviceBootloader {
      */
     static std::vector<std::uint8_t> getEmbeddedBootloaderBinary(Type type = DEFAULT_TYPE);
 
+    /// Default constructor is not available; a DeviceInfo is required.
     DeviceBootloader() = delete;
 
     /**

include/depthai/device/Version.hpp

@@ -25,6 +25,7 @@ struct Version {
             const std::optional<uint16_t>& preReleaseVersion = std::nullopt,
             const std::string& buildInfo = "");
 
+    /// Construct Version with build metadata and no pre-release tag.
     Version(unsigned major, unsigned minor, unsigned patch, const std::string& buildInfo)
         : Version(major, minor, patch, PreReleaseType::NONE, std::nullopt, buildInfo) {}
     bool operator==(const Version& other) const;
@@ -54,4 +55,4 @@ struct Version {
     spimpl::impl_ptr<Impl> pimpl;
 };
 
-}  // namespace dai
+}  // namespace dai