Skip to content

Commit

Permalink
docs: warn if undocumented (to be enabled folder by folder)
Browse files Browse the repository at this point in the history
  • Loading branch information
strasdat committed Sep 29, 2023
1 parent 9d53a31 commit 223c656
Show file tree
Hide file tree
Showing 20 changed files with 182 additions and 52 deletions.
3 changes: 3 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -6,3 +6,6 @@ venv
scripts/venv.tar.gz
*.so
Cargo.lock
docs/api_reference/html/
docs/api_reference/projects/
target/
2 changes: 2 additions & 0 deletions cpp/farm_ng/core/logging/expected.h
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,9 @@

namespace farm_ng {

/// An error, meant to be used with `Expected`.
struct Error {
/// A list (or stack) of error details.
std::vector<ErrorDetail> details;
};

Expand Down
43 changes: 29 additions & 14 deletions cpp/farm_ng/core/logging/logger.h
Original file line number Diff line number Diff line change
Expand Up @@ -40,44 +40,53 @@ FARM_ENUM(

std::string stringFromLogLevel(LogLevel level);

// A logger that writes to std::cerr (and optionally to a file).
/// A logger that writes to std::cerr (and optionally to a file).
class StreamLogger {
public:
/// Details of the disk logging implementation.
struct DiskLogging {
// if log_dir_!=nullopt, then logging to a file is enabled.
/// if log_dir_!=nullopt, then logging to a file is enabled.
std::optional<std::filesystem::path> log_dir;
/// The file stream to write to.
std::ofstream log_file_stream;
/// Mutex guarding the file stream.
std::mutex log_file_mutex;
};

// The header format is a {fmt}-style format string that may include the
// named arguments {level}, {text}, {file}, {line}, {function}, {time}.
/// The header format is a {fmt}-style format string that may include the
/// named arguments {level}, {text}, {file}, {line}, {function}, {time}.
void setHeaderFormat(std::string const& str);

/// Get the current header format.
std::string getHeaderFormat() const;

// Set the runtime log level
/// Set the runtime log level
void setLogLevel(LogLevel level);

/// Get the current runtime log level
LogLevel getLogLevel();

// Set the directory where log files are written to. A file named
// "text.log" will be created in this directory.
//
// If the directory does not exist, or is not writable, false is returned.
/// Set the directory where log files are written to. A file named
/// "text.log" will be created in this directory.
///
/// If the directory does not exist, or is not writable, false is returned.
bool trySetLogDir(std::filesystem::path const& path) noexcept;

// Get the directory where log files are written to. Returns nullopt if no
// directory has been set.
/// Get the directory where log files are written to. Returns nullopt if no
/// directory has been set.
std::optional<std::filesystem::path> getLogDir() const noexcept;

// A type-erased generator of timestamp strings
/// A type-erased generator of timestamp strings
struct LogClock {
/// Generate a timestamp string
std::function<std::string()> now;
};

// Set the clock used to produce timestamps
/// Set the clock used to produce timestamps
void setLogClock(LogClock log_clock);

template <typename... TT>
/// Generic logging function. Use the FARM_* macros instead.
template <class... TT>
inline void log(
LogLevel log_level,
std::string const& header_text,
Expand Down Expand Up @@ -116,6 +125,7 @@ class StreamLogger {
}
}

/// Log function. Use the FARM_* macros instead.
void log(
LogLevel log_level,
std::string const& header_text,
Expand Down Expand Up @@ -424,9 +434,14 @@ struct CheckNear<TT, std::enable_if_t<std::is_arithmetic_v<TT>, void>> {
FARM_FORMAT(__VA_ARGS__))

namespace farm_ng {

/// Expected error stack trace line
struct ErrorDetail {
/// File where the error occurred
std::string file;
/// Line where the error occurred
int line;
/// Error message
std::string msg;
};

Expand Down
2 changes: 2 additions & 0 deletions cpp/farm_ng/core/logging/test_common.h
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,7 @@

namespace farm_ng::testing {

/// Captures stdout and stderr.
class CaptureStdErr {
public:
CaptureStdErr() {
Expand All @@ -28,6 +29,7 @@ class CaptureStdErr {
}
~CaptureStdErr() { std::cerr.rdbuf(orig_std_err_buffer_); }

/// Returns the captured output.
std::string buffer() const { return buffer_.str(); }

private:
Expand Down
36 changes: 19 additions & 17 deletions cpp/farm_ng/core/misc/shared.h
Original file line number Diff line number Diff line change
Expand Up @@ -21,36 +21,37 @@

namespace farm_ng {

// Represents a Non-nullable pointer with shared ownership
// Is essentially an adapter between std::shared_ptr and farm_ng::Expected
/// Represents a Non-nullable pointer with shared ownership
/// Is essentially an adapter between std::shared_ptr and farm_ng::Expected
template <class TT>
class Shared {
public:
/// The type of the expected object returned by tryFrom()
using ExpectedT = farm_ng::Expected<Shared<TT>>;

// Default constructable only if T is

template <class TTT = TT>
Shared() requires(std::is_default_constructible<TTT>::value)
: non_null_shared_(std::make_shared<TTT>()) {}

// Rule of 5

// Destructor
/// Destructor (Rule of 5, 1/5)
~Shared() noexcept = default;

// Copy constr/assignment
/// Copy constr (Rule of 5, 2/5)
Shared(Shared const&) = default;

/// Copy assignment (Rule of 5, 3/5)
Shared& operator=(Shared const&) = default;

// TODO: Better to not have move constructor and assignment operator, but it
// is currently used in downstream code

// Move constr/assignment (mimic copy constructor)
/// Move constr (mimic copy constructor) (Rule of 5, 4/5)
Shared(Shared<TT>&& o) noexcept : non_null_shared_(o.non_null_shared_) {
// We mustn't move the internal shared_ptr
// because that would break the invariant.
}

/// Move assignment (mimic copy assignment) (Rule of 5, 5/5)
Shared<TT>& operator=(Shared<TT>&& o) noexcept {
// We maintain the invariant since
// o.non_null_shared_ must also be valid
Expand All @@ -68,19 +69,19 @@ class Shared {

/// From TDerived constructors

// Copy constructor from derived bases
/// Copy constructor from derived bases
template <DerivedFrom<TT> TDerived>
Shared(Shared<TDerived> const& other) noexcept
: non_null_shared_(other.sharedPtr()) {}

// Construct from shared_ptr
/// Construct from shared_ptr
template <DerivedFrom<TT> TDerived>
Shared(std::shared_ptr<TDerived> const& panic_if_null) noexcept
: non_null_shared_(panic_if_null) {
FARM_ASSERT_NE(non_null_shared_, nullptr);
}

// Take ownership from unique_ptr
/// Take ownership from unique_ptr
template <DerivedFrom<TT> TDerived>
Shared(std::unique_ptr<TDerived>&& panic_if_null) noexcept
: non_null_shared_(std::move(panic_if_null)) {
Expand All @@ -90,7 +91,7 @@ class Shared {
/// Construct from a possibly null shared_ptr
/// The return value is an object containing either a non-null Shared object
/// pointer,
// or an farm_ng::Error object
/// or an farm_ng::Error object
static ExpectedT tryFrom(std::shared_ptr<TT> const& maybe_null) noexcept {
if (!maybe_null) {
return FARM_UNEXPECTED("is null");
Expand Down Expand Up @@ -143,20 +144,21 @@ class Shared {
/// Returns the interior object which is guaranteed to be available
TT const* operator->() const { return non_null_shared_.get(); }

// Implicit conversion to a nullable std::shared_ptr okay
/// Implicit conversion to a nullable std::shared_ptr okay
operator std::shared_ptr<TT>() const { return sharedPtr(); }

// Return a nullable shared_ptr<T> from this Shared<T> object
/// Return a nullable shared_ptr<T> from this Shared<T> object
[[nodiscard]] std::shared_ptr<TT> sharedPtr() const {
return non_null_shared_;
}

// Return the raw point from this Shared<T> object
/// Return the raw point from this Shared<T> object
[[nodiscard]] TT const* ptr() const { return sharedPtr().get(); }

// Return the raw point from this Shared<T> object
/// Return the raw point from this Shared<T> object
TT* ptr() { return sharedPtr().get(); }

/// Compare two Shared<T> objects for equality
bool operator==(Shared<TT> const& rhs) const noexcept {
return this->non_null_shared_ == rhs.non_null_shared_;
}
Expand Down
4 changes: 4 additions & 0 deletions cpp/farm_ng/core/misc/stopwatch.h
Original file line number Diff line number Diff line change
Expand Up @@ -67,9 +67,13 @@ class StopwatchSingleton {

/// Container for statistics on stopwatch timers.
struct StopwatchStats {
/// Mean time of timer.
double mean;
/// Minimum time of timer.
double min;
/// Maximum time of timer.
double max;
/// Number of times timer was called.
int num;
};

Expand Down
40 changes: 34 additions & 6 deletions cpp/farm_ng/core/misc/time_series.h
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,7 @@ concept StampedValue = requires(TType m) {
{ getStamp<TType>(m) } -> sophus::concepts::ConvertibleTo<double>;
};

/// Interpolate between two values.
template <class TType>
auto interpolate(
TType const& foo_from_bar, TType const& foo_from_daz, double p = 0.5)
Expand All @@ -51,18 +52,22 @@ concept InterpolativeValue = StampedValue<TType> &&
{ interpolate<TType>(m, m, p) } -> sophus::concepts::ConvertibleTo<TType>;
};

// New type to specify maximal allowed time gap for interpolation.
/// New type to specify maximal allowed time gap for interpolation.
struct MaxGap {
/// Construct from double.
explicit MaxGap(double time_duration) : time_duration(time_duration) {}

/// Maximal allowed time gap for interpolation.
double time_duration;
};

// New type to specify nearness to consider two values near in timeseries (e.g.
// to skip interpolation calculation).
/// New type to specify nearness to consider two values near in timeseries (e.g.
/// to skip interpolation calculation).
struct NearnessThreshold {
/// Construct from double.
explicit NearnessThreshold(double time_thr) : time_thr(time_thr) {}

/// Nearness threshold.
double time_thr;
};

Expand All @@ -81,8 +86,11 @@ struct NearnessThreshold {
template <time_series::StampedValue TValueWithStamp>
class TimeSeries {
public:
/// ValueWithStamp is a StampedValue.
using ValueWithStamp = TValueWithStamp;
/// Container type.
using Container = std::deque<ValueWithStamp>;
/// ConstIterator type.
using ConstIterator = typename Container::const_iterator;

/// Returns true if there are no Values in series.
Expand Down Expand Up @@ -145,11 +153,15 @@ class TimeSeries {
: *it_greatest_lower_bound;
}

/// Bounds used in findBounds.
struct Bounds {
/// Largest lower bound.
ValueWithStamp largest_lower_bound;
/// Smallest upper bound.
ValueWithStamp smallest_upper_bound;
};

/// Find bounds for query_stamp.
Expected<Bounds> findBounds(double query_stamp) const {
auto it_smallest_upper_bound = findSmallestUpperBound(query_stamp);
if (it_smallest_upper_bound == cbegin() &&
Expand Down Expand Up @@ -242,23 +254,39 @@ class TimeSeries {
return this->interpolatedValueImpl(
query_stamp, maximal_time_gap.time_duration);
}

/// Returns first value in series.
///
/// Precondition: series is not empty.
ValueWithStamp const& front() const { return time_ordered_series_.front(); }

/// Returns last value in series.
///
/// Precondition: series is not empty.
ValueWithStamp const& back() const { return time_ordered_series_.back(); }

/// Removes all values from series.
void clear() { return time_ordered_series_.clear(); }

/// Removes first value from series.
///
/// Precondition: series is not empty.
void pop_front() { return time_ordered_series_.pop_front(); }

/// Removes last value from series.
///
/// Precondition: series is not empty.
void pop_back() { return time_ordered_series_.pop_back(); }

// begin of series.
/// begin of series.
ConstIterator begin() const { return time_ordered_series_.begin(); }

/// begin of series.
ConstIterator cbegin() const { return time_ordered_series_.cbegin(); }

// end of series.
/// end of series.
ConstIterator end() const { return time_ordered_series_.end(); }

/// end of series.
ConstIterator cend() const { return time_ordered_series_.cend(); }

private:
Expand Down
3 changes: 3 additions & 0 deletions cpp/farm_ng/core/misc/uri.h
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,8 @@

namespace farm_ng {

/// Uri is a Uniform Resource Identifier.
///
/// https://en.wikipedia.org/w/index.php?title=Uniform_Resource_Identifier&oldid=1072892451#Syntax
struct Uri {
Uri() {}
Expand Down Expand Up @@ -51,6 +53,7 @@ struct Uri {
/// For instance: '?in=input_channel_name`.
std::string query;

/// Lexicographical comparison of uri.
friend inline bool operator<(Uri const& lhs, Uri const& rhs) {
return lhs.string() < rhs.string();
}
Expand Down
2 changes: 2 additions & 0 deletions cpp/farm_ng/core/plotting/plotting_component.h
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,8 @@

namespace farm_ng {

/// A plotting component sink which publishes messages to a remote plotting
/// service.
class PlottingComponent {
public:
static Shared<PlottingComponent> create(
Expand Down
2 changes: 2 additions & 0 deletions cpp/farm_ng/core/plotting/remote_plotting_client.h
Original file line number Diff line number Diff line change
Expand Up @@ -23,8 +23,10 @@ namespace farm_ng {

static uint64_t const kPlottingComponentDefaultPort = 1980;

/// A plotting component that can be used to plot curves and images.
class RemotePlottingClient {
public:
/// Parameters for the plotting component.
struct Params {
std::string host = "localhost";
uint32_t port = kPlottingComponentDefaultPort;
Expand Down
Loading

0 comments on commit 223c656

Please sign in to comment.