docs: warn if undocumented (cpp code farm-ng/core)

cpp/farm_ng/core/pipeline/context.h

@@ -18,9 +18,6 @@
 
 #include <boost/asio/io_service.hpp>
 #include <boost/asio/strand.hpp>
-// #include <boost/asio/executor_work_guard.hpp>
-// #include <boost/asio/io_context.hpp>
-// #include <boost/asio/io_context_strand.hpp>
 
 #include <iostream>
 #include <set>
@@ -38,11 +35,12 @@ class Output;
 /// Contains the execution state context.
 class Context {
  public:
-  // using WorkGuard =
-  // boost::asio::executor_work_guard<boost::asio::io_context::executor_type>;
+  /// boost::asio::io_service::work
   using WorkGuard = boost::asio::io_service::work;
-  // boost::asio::io_contex
+  /// The IO context type.
   using IoContext = boost::asio::io_service;
+  /// See:
+  /// https://www.boost.org/doc/libs/1_60_0/doc/html/boost_asio/overview/core/strands.html
   using Strand = Context::IoContext::strand;
 
   /// Default constructor of a context.
@@ -57,8 +55,8 @@ class Context {
   /// Run the `io_context`.
   void run();
 
-  // Restart the context and run, to be used when context has stopped
-  // i.e. when all posted jobs are complete and no workguard.
+  /// Restart the context and run, to be used when context has stopped
+  /// i.e. when all posted jobs are complete and no workguard.
   void restartAndRun();
 
   /// clear the work for advanced use cases where you want to execute a finite

cpp/farm_ng/core/pipeline/input.h

@@ -28,8 +28,10 @@ namespace farm_ng {
 /// The configuration of an ``Input`` class.
 class InputConfig {
  public:
+  /// Default constructor, takes its `max_queue_length`.
   explicit InputConfig(size_t max_queue_length = 0);
 
+  /// The maximum queue length of the input.
   size_t max_queue_length;
 };
 

cpp/farm_ng/core/plotting/plotting_component.h

@@ -28,11 +28,15 @@ namespace farm_ng {
 /// service.
 class PlottingComponent {
  public:
+  /// Creates a plotting component.
   static Shared<PlottingComponent> create(
       Context const& ctx, RemotePlottingClient::Params const& params);
   virtual ~PlottingComponent() = default;
 
+  /// Connect must be called before the component is run.
   virtual void connect() = 0;
+
+  /// Returns the input channel for messages to be plotted.
   virtual Input<std::vector<plotting::Message>>& inMessages() = 0;
 };
 

cpp/farm_ng/core/plotting/remote_plotting_client.h

@@ -28,15 +28,20 @@ class RemotePlottingClient {
  public:
   /// Parameters for the plotting component.
   struct Params {
+    /// The host of the plotting service.
     std::string host = "localhost";
+    /// The port of the plotting service.
     uint32_t port = kPlottingComponentDefaultPort;
+    /// The rate limit in Hz.
     double rate_limit_hz = 2.0;
   };
 
   virtual ~RemotePlottingClient() = default;
 
+  /// Creates a plotting component.
   static Shared<RemotePlottingClient> createAndConnect(Params const& params);
 
+  /// Returns the input channel for messages to be plotted.
   virtual void onMessages(std::vector<plotting::Message> const& messages) = 0;
 };
 

cpp/farm_ng/core/plotting/types.h

@@ -36,10 +36,13 @@ FARM_ENUM(LineType, (points, line_strip));
 ///
 /// TODO: Redesign this to be more general and more usable.
 struct CurveResetPredicate {
+  /// Returns a predicate that does reset the curve.
   static CurveResetPredicate replace() {
     return CurveResetPredicate{
         .clear_x_smaller_than = std::numeric_limits<double>::max()};
   }
+
+  /// Condition for clearing part of the curve.
   std::optional<double> clear_x_smaller_than = std::nullopt;
 };
 
@@ -93,29 +96,38 @@ FARM_STRUCT(
 
 /// A colored rectangle.
 struct ColoredRect {
-  // typedefs for FARM_PROTO_CONV_IMPL to work
+  /// Number of fields (for FARM_PROTO_CONV_IMPL to work)
   static int constexpr kNumFields = 2;
+
+  /// Tuple of field names (for FARM_PROTO_CONV_IMPL to work)
   static std::array<std::string_view, kNumFields> constexpr kFieldNames = {
       "color", "region"};
+
+  /// Tuple of field types (for FARM_PROTO_CONV_IMPL to work)
   using FieldTypes = std::tuple<sophus::Region2F64, sophus::Color>;
   static_assert(
       std::tuple_size_v<FieldTypes> == kNumFields,
       "Tuple size mismatch. Make sure to update kNumFields and kFieldNames when"
       " adding/modifying fields.");
 
+  /// Vertical Line
   static ColoredRect xLine(
       sophus::Color const& color,
       double x,
       sophus::RegionF64 const& y_range,
       double thickness = 0.01);
 
+  /// Horizontal line
   static ColoredRect yLine(
       sophus::Color const& color,
       double y,
       sophus::RegionF64 const& x_range,
       double thickness = 0.01);
 
+  /// Color of the rectangle.
   sophus::Color color{};
+
+  /// Region the rectangle describes.
   sophus::Region2F64 region = sophus::Region2F64::empty();
 };
 

cpp/farm_ng/core/proto_conv/image/conv.h

@@ -29,9 +29,10 @@ FARM_PROTO_CONV_TRAIT(sophus::AnyImage<>, core::proto::DynImage);
 Expected<sophus::IntensityImage<>> intensityImageFromProto(
     core::proto::DynImage const& proto);
 
-/// Converts a sophus::IntensityImage<> to a proto.
+/// Associates a proto type to a sophus::IntensityImage<>.
 template <>
 struct ToProtoTrait<sophus::IntensityImage<>> {
+  /// proto type
   using ProtoType = core::proto::DynImage;
 };
 

cpp/farm_ng/core/prototools/event_log_reader.h

@@ -25,15 +25,11 @@
 #include <string>
 
 namespace farm_ng {
-/// Exception thrown when the event log file does not exist.
-class EventLogEof : public std::runtime_error {
- public:
-  explicit EventLogEof(std::string const& what) : std::runtime_error(what) {}
-};
 
 /// Exception thrown when the event log file does not exist.
 class EventLogExist : public std::runtime_error {
  public:
+  /// From error message string.
   explicit EventLogExist(std::string const& what) : std::runtime_error(what) {}
 };
 
@@ -44,20 +40,28 @@ struct EventLogReaderBase {
   virtual ~EventLogReaderBase() {}
 
   virtual Expected<std::pair<core::proto::Event, std::streampos>>
+
+  /// Implementation detail of readNextEvent.
   readNextEventImpl(std::string* payload) noexcept = 0;
 
+  /// Returns an index of all the events contained in the file.
   virtual std::vector<EventLogPos>& index() = 0;
 
-  virtual auto readPayload(
+  /// reads payload for event at pos
+  [[nodiscard]] virtual auto readPayload(
       core::proto::Event const& event, std::streampos pos) noexcept
       -> Expected<std::string> = 0;
 
+  /// Resets the reader to the beginning of the file.
   [[nodiscard]] virtual Expected<Success> reset() noexcept = 0;
 };
 
 /// Position in the event log file.
 class EventLogPos {
  public:
+  /// Create a new EventLogPos.
+  ///
+  /// A reference to the EventLogReader is stored in a weak_ptr.
   EventLogPos(
       core::proto::Event event,
       std::streampos pos,
@@ -66,7 +70,10 @@ class EventLogPos {
         pos_(pos),
         reader_weak_ptr_(reader_impl.sharedPtr()) {}
 
+  /// Returns the event.
   core::proto::Event const& event() const;
+
+  /// Returns the payload.
   Expected<std::string> readPayload() const;
 
  private:
@@ -91,20 +98,20 @@ class EventLogReader {
   static Expected<EventLogReader> fromPath(
       std::filesystem::path const& log_path) noexcept;
 
-  // This function throws EventLogEof if the end of file is reached or a message
-  // can not be decoded (typically due to an interrupted process).
+  /// This function returns error if the end of file is reached or a message
+  /// can not be decoded (typically due to an interrupted process).
   Expected<EventLogPos> readNextEvent(std::string* payload = nullptr) noexcept;
 
-  // Returns an index of all the events contained in the file.  This function
-  // caches the index, so its only computed once; the index requires seeking
-  // through the entire file and decoding the events.  It should be fast as
-  // payloads are skipped with seekg and not decoded.
+  /// Returns an index of all the events contained in the file.  This function
+  /// caches the index, so its only computed once; the index requires seeking
+  /// through the entire file and decoding the events.  It should be fast as
+  /// payloads are skipped with seekg and not decoded.
   std::vector<EventLogPos> const& getIndex() noexcept;
 
   /// Returns the path including the fileaname
   [[nodiscard]] std::filesystem::path getPath() const noexcept;
 
-  /// Reset the writer to the beginning of the file
+  /// Reset the reader to the beginning of the file
   [[nodiscard]] Expected<Success> reset() noexcept;
 
  private:
@@ -117,11 +124,15 @@ class EventLogReader {
 
 /// Compare two EventLogPos by their timestamp.
 struct EventTimeCompareClockAndSemantics {
+  /// The clock_name and semantics to use for comparison.
   std::string clock_name;
+
+  /// meaning of that clock / type of timestamp
   std::string semantics;
-  // precondition:
-  //    lhs and rhs both contain a stamp from the target clock_name and
-  //    semantics.
+
+  /// precondition:
+  ///    lhs and rhs both contain a stamp from the target clock_name and
+  ///    semantics.
   bool operator()(EventLogPos const& lhs, EventLogPos const& rhs) const;
 };
 

cpp/farm_ng/core/prototools/event_log_writer.h

@@ -41,6 +41,8 @@ class EventLogWriter {
       google::protobuf::Message const& message,
       std::vector<core::proto::Timestamp> const& timestamps =
           std::vector<core::proto::Timestamp>()) noexcept;
+
+  /// Writes an incoming protobuf in the log file
   void write(
       std::string const& path,
       google::protobuf::Message const& message,

docs/api_reference/doxyfile

@@ -3,16 +3,19 @@ PROJECT_NAME           = "farm-ng-core"
 INPUT                  = ../../cpp/farm_ng \
                          ../../cpp/sophus \
                          ../../py/farm_ng
+FILE_PATTERNS          = *.h \
+                         *.hpp \
+                         *.ipp
 EXCLUDE_PATTERNS       = "*/sympy/*"
 RECURSIVE              = YES
 ENABLE_PREPROCESSING   = YES
 MACRO_EXPANSION        = YES
-EXTRACT_ALL          = YES
+EXTRACT_ALL            = YES
 WARN_AS_ERROR          = YES
-WARNINGS              = YES
-WARN_IF_UNDOCUMENTED  = YES
-WARN_IF_DOC_ERROR     = YES
-WARN_NO_PARAMDOC      = YES
+WARNINGS               = YES
+WARN_IF_UNDOCUMENTED   = YES
+WARN_IF_DOC_ERROR      = YES
+WARN_NO_PARAMDOC       = YES
 EXPAND_ONLY_PREDEF     = NO
 SKIP_FUNCTION_MACROS   = NO
 AUTOLINK_SUPPORT       = YES

docs/api_reference/doxyfile_cpp_farm_ng_warn_as_error

@@ -1,8 +1,6 @@
 DOXYFILE_ENCODING      = UTF-8
 PROJECT_NAME           = "farm-ng-core"
-INPUT                  = ../../cpp/farm_ng/core/enum \
-                         ../../cpp/farm_ng/core/logging \
-                         ../../cpp/farm_ng/core/misc
+INPUT                  = ../../cpp/farm_ng/core
 FILE_PATTERNS          = *.h \
                          *.hpp \
                          *.ipp
@@ -11,9 +9,9 @@ RECURSIVE              = YES
 ENABLE_PREPROCESSING   = YES
 MACRO_EXPANSION        = YES
 WARN_AS_ERROR          = YES
-WARNINGS              = YES
-WARN_IF_UNDOCUMENTED  = YES
-WARN_IF_DOC_ERROR     = YES
+WARNINGS               = YES
+WARN_IF_UNDOCUMENTED   = YES
+WARN_IF_DOC_ERROR      = YES
 EXPAND_ONLY_PREDEF     = NO
 SKIP_FUNCTION_MACROS   = NO
 AUTOLINK_SUPPORT       = YES