Documentation

Author: anderspkd

doc/layout.xml

@@ -10,33 +10,33 @@
       <tab type="modulelist" visible="yes" title="" intro=""/>
       <tab type="modulemembers" visible="yes" title="" intro=""/>
     </tab>
-    <tab type="namespaces" visible="yes" title="">
+    <tab type="namespaces" visible="no" title="">
       <tab type="namespacelist" visible="yes" title="" intro=""/>
       <tab type="namespacemembers" visible="yes" title="" intro=""/>
     </tab>
-    <tab type="concepts" visible="yes" title="">
+    <tab type="concepts" visible="no" title="">
     </tab>
-    <tab type="interfaces" visible="yes" title="">
+    <tab type="interfaces" visible="no" title="">
       <tab type="interfacelist" visible="yes" title="" intro=""/>
       <tab type="interfaceindex" visible="$ALPHABETICAL_INDEX" title=""/>
       <tab type="interfacehierarchy" visible="yes" title="" intro=""/>
     </tab>
-    <tab type="classes" visible="yes" title="">
+    <tab type="classes" visible="no" title="">
       <tab type="classlist" visible="yes" title="" intro=""/>
       <tab type="classindex" visible="$ALPHABETICAL_INDEX" title=""/>
       <tab type="hierarchy" visible="yes" title="" intro=""/>
       <tab type="classmembers" visible="yes" title="" intro=""/>
     </tab>
-    <tab type="structs" visible="yes" title="">
+    <tab type="structs" visible="no" title="">
       <tab type="structlist" visible="yes" title="" intro=""/>
       <tab type="structindex" visible="$ALPHABETICAL_INDEX" title=""/>
     </tab>
-    <tab type="exceptions" visible="yes" title="">
+    <tab type="exceptions" visible="no" title="">
       <tab type="exceptionlist" visible="yes" title="" intro=""/>
       <tab type="exceptionindex" visible="$ALPHABETICAL_INDEX" title=""/>
       <tab type="exceptionhierarchy" visible="yes" title="" intro=""/>
     </tab>
-    <tab type="files" visible="yes" title="">
+    <tab type="files" visible="no" title="">
       <tab type="filelist" visible="yes" title="" intro=""/>
       <tab type="globals" visible="yes" title="" intro=""/>
     </tab>

include/scl/argparser.h

@@ -124,12 +124,21 @@ class ProgramOptions {
   std::unordered_map<std::string_view, bool> m_flags;
 };
 
+/**
+ * @brief Get a command-line provided option as a boolean.
+ */
 template <>
 bool ProgramOptions::get<bool>(std::string_view name) const;
 
+/**
+ * @brief Get a command-line provided option as an int.
+ */
 template <>
 int ProgramOptions::get<int>(std::string_view name) const;
 
+/**
+ * @brief Get a command-line provided option as an std::string.
+ */
 template <>
 std::size_t ProgramOptions::get<std::size_t>(std::string_view name) const;
 

include/scl/bitmap.h

@@ -266,12 +266,24 @@ class Bitmap {
  */
 template <>
 struct Serializer<Bitmap> {
+
+  /**
+   * @brief Returns the size of a bitmap.
+   */
   static std::size_t sizeOf(const Bitmap& bm) {
     return Serializer<Bitmap::ContainerType>::sizeOf(bm.m_bits);
   }
+
+  /**
+   * @brief Write the bitmap to a buffer.
+   */
   static std::size_t write(const Bitmap& bm, unsigned char* buf) {
     return Serializer<Bitmap::ContainerType>::write(bm.m_bits, buf);
   }
+
+  /**
+   * @brief Reads a bitmap from a buffer.
+   */
   static std::size_t read(Bitmap& bm, const unsigned char* buf) {
     return Serializer<Bitmap::ContainerType>::read(bm.m_bits, buf);
   }

include/scl/coro/promise.h

@@ -23,7 +23,6 @@
 #include <utility>
 #include <variant>
 
-#include "scl/coro/batch.h"
 #include "scl/coro/future.h"
 #include "scl/coro/sleep_awaiter.h"
 

include/scl/coro/runtime.h

@@ -21,7 +21,6 @@
 #include <functional>
 #include <list>
 
-#include "scl/coro/batch.h"
 #include "scl/coro/future.h"
 #include "scl/coro/promise.h"
 #include "scl/coro/sleep_awaiter.h"

include/scl/coro/task.h

@@ -20,7 +20,6 @@
 #include <coroutine>
 #include <utility>
 
-#include "scl/coro/batch.h"
 #include "scl/coro/promise.h"
 
 namespace scl {

include/scl/net/tcp/network.h

@@ -18,8 +18,8 @@
 #pragma once
 
 #include "scl/coro/task.h"
-#include "scl/net/config.h"
 #include "scl/net/network.h"
+#include "scl/net/tcp/config.h"
 
 namespace scl {
 

include/scl/protocol.h

@@ -140,12 +140,22 @@ struct Result {
     return Result{.next = std::move(next), .output = output};
   }
 
+  /**
+   * @brief A pointer to the next Protocol to run.
+   */
   std::unique_ptr<Protocol> next;
+
+  /**
+   * @brief The protocols output.
+   */
   std::any output;
 };
 
 /**
  * @brief Run a protocol.
+ *
+ * This function runs a protocol. A provided callback is invoked every time the
+ * protocol produces an output.
  */
 template <typename CALLBACK>
 Task<void> runProtocol(std::unique_ptr<Protocol> protocol,
@@ -162,6 +172,14 @@ Task<void> runProtocol(std::unique_ptr<Protocol> protocol,
   }
 }
 
+/**
+ * @brief Run a protocol that returns a value.
+ *
+ * This function runs a protocol, returning the non-void value returned by its
+ * last step.
+ *
+ * @throws std::runtime_error if the provided protocol has no output.
+ */
 template <typename R>
 Task<R> runProtocol(std::unique_ptr<Protocol> protocol, Env& env) {
   Result result;

include/scl/serialization.h

@@ -75,15 +75,25 @@ concept Serializable =
 template <typename T>
   requires(std::is_trivially_copyable_v<T>)
 struct Serializer<T> {
+
+  /**
+   * @brief Determine the size of a value.
+   */
   static constexpr std::size_t sizeOf(const T& /* ignored */) {
     return sizeof(T);
   }
 
+  /**
+   * @brief Write the value to a buffer.
+   */
   static constexpr std::size_t write(const T& obj, unsigned char* out) {
     std::memcpy(out, &obj, sizeof(T));
     return sizeOf(obj);
   }
 
+  /**
+   * @brief Read a value from a buffer.
+   */
   static constexpr std::size_t read(T& obj, const unsigned char* in) {
     std::memcpy(&obj, in, sizeof(T));
     return sizeOf(obj);
@@ -95,8 +105,16 @@ struct Serializer<T> {
  */
 template <Serializable T>
 struct Serializer<std::vector<T>> {
+
+  /**
+   * @brief Type used to denote the size of the vector.
+   */
   using VecSizeType = std::uint32_t;
 
+
+  /**
+   * @brief Get the bytes required to write \p vec with this serializer.
+   */
   static constexpr std::size_t sizeOf(const std::vector<T>& vec) {
     auto total_size = sizeof(VecSizeType);
     for (const auto& v : vec) {
@@ -105,6 +123,9 @@ struct Serializer<std::vector<T>> {
     return total_size;
   }
 
+  /**
+   * @brief Write a vector to a buffer.
+   */
   static constexpr std::size_t write(const std::vector<T>& vec,
                                      unsigned char* out) {
     const auto vec_size = static_cast<VecSizeType>(vec.size());
@@ -115,6 +136,9 @@ struct Serializer<std::vector<T>> {
     return written;
   }
 
+  /**
+   * @brief Read a vector from a buffer.
+   */
   static constexpr std::size_t read(std::vector<T>& vec,
                                     const unsigned char* in) {
     VecSizeType vec_size = 0;

include/scl/simulation/channel.h

@@ -25,8 +25,19 @@
 
 namespace scl::details {
 
+/**
+ * @brief Channel implementation for simulations.
+ * @ingroup net-sim
+ *
+ * SimulatedChannel implements Channel for non-local parties in simulations. The
+ * main responsibilities of this class are (1) calling a Transport object with
+ * the stuff to be sent/received, and (2) generating the right Events.
+ */
 class SimulatedChannel final : public Channel {
  public:
+  /**
+   * @brief Create a new SimulatedChannel.
+   */
   static std::shared_ptr<Channel> create(ChannelId id,
                                          Context ctx,
                                          std::shared_ptr<Transport> transport) {
@@ -36,19 +47,44 @@ class SimulatedChannel final : public Channel {
   SimulatedChannel(ChannelId id,
                    Context ctx,
                    std::shared_ptr<Transport> transport)
-      : m_id(id), m_ctx(ctx), m_transport(transport) {}
+      : m_id(id), m_ctx(ctx), m_transport(transport), m_closed(false) {}
 
+  /**
+   * @brief Closes the channel.
+   */
   void close() override;
+
+  /**
+   * @brief Send a packet.
+   */
   Task<void> send(Packet&& packet) override;
+
+  /**
+   * @brief Send a packet.
+   */
   Task<void> send(const Packet& packet) override;
+
+  /**
+   * @brief Recv a packet.
+   */
   Task<Packet> recv() override;
+
+  /**
+   * @brief Attempt to receive a packet within a provied timeout.
+   */
   Task<std::optional<Packet>> recv(Time::Duration timeout) override;
+
+  /**
+   * @brief Poll the channel for data.
+   */
   Task<bool> poll() override;
 
  private:
   ChannelId m_id;
   Context m_ctx;
   std::shared_ptr<Transport> m_transport;
+
+  bool m_closed;
 };
 
 }  // namespace scl::details