doxy

library/include/ipfs_client/crypto/hasher.h

@@ -13,7 +13,10 @@ class Hasher {
  public:
   virtual ~Hasher() noexcept {}
 
-  virtual std::optional<std::vector<Byte>> hash(ByteView) = 0;
+  /*! @param bytes Bytes to hash
+   *  @return The digest or nullopt if there was an error
+   */
+  virtual std::optional<std::vector<Byte>> hash(ByteView bytes) = 0;
 };
 }  // namespace ipfs::crypto
 

library/include/ipfs_client/crypto/signature_verifier.h

@@ -11,6 +11,8 @@ namespace ipfs::crypto {
 class SignatureVerifier {
  public:
   virtual ~SignatureVerifier() noexcept {}
+  /*! Non-owned bytes
+   */
   using ByteView = ipfs::ByteView;
   virtual bool VerifySignature(ByteView signature,
                                ByteView data,

library/include/ipfs_client/ctx/cbor_parser.h

@@ -14,7 +14,10 @@ namespace ipfs::ctx {
  */
 class CborParser {
  public:
-  virtual std::unique_ptr<DagCborValue> Parse(ByteView) = 0;
+  /*! @param cbor The CBOR to parse
+   *  @return The DOM value, or NULL if there was an error
+   */
+  virtual std::unique_ptr<DagCborValue> Parse(ByteView cbor) = 0;
   virtual ~CborParser() noexcept {}
 };
 }  // namespace ipfs::ctx

library/include/ipfs_client/ctx/dns_txt_lookup.h

@@ -10,6 +10,8 @@ namespace ipfs::ctx {
  */
 class DnsTxtLookup {
  public:
+  /*! Callback for if usable result was achieved
+   */
   using DnsTextResultsCallback =
       std::function<void(std::vector<std::string> const&)>;
   using DnsTextCompleteCallback = std::function<void(void)>;

library/include/ipfs_client/ctx/gateway_config.h

@@ -13,6 +13,10 @@ namespace ipfs::ctx {
 class GatewayConfig {
  public:
   virtual ~GatewayConfig() noexcept {}
+  /*! Position-based access (indexing)
+   *  @param index The 0-based index of the gateway in question
+   *  @return The spec for the gateway iff index < count of gateways, nullopt otherwise
+   */
   virtual std::optional<GatewaySpec> GetGateway(std::size_t index) const = 0;
   virtual unsigned GetGatewayRate(std::string_view url_prefix) = 0;
   virtual int GetTypeAffinity(std::string_view url_prefix,

library/include/ipfs_client/ctx/http_api.h

@@ -10,6 +10,8 @@ namespace ipfs::ctx {
  */
 class HttpApi {
  public:
+  /*! Description of the request to be sent
+   */
   using ReqDesc = ::ipfs::HttpRequestDescription;
   using Hdrs = std::function<std::string(std::string_view)>;
   using OnComplete = std::function<void(std::int16_t, std::string_view, Hdrs)>;

library/include/ipfs_client/ctx/json_parser.h

@@ -14,7 +14,10 @@ namespace ipfs::ctx {
 class JsonParser {
  public:
   virtual ~JsonParser() noexcept {}
-  virtual std::unique_ptr<DagJsonValue> Parse(std::string_view) = 0;
+  /*! @param json The JSON text to parse
+   *  @return The DOM object or NULL if parsing failed.
+   */
+  virtual std::unique_ptr<DagJsonValue> Parse(std::string_view json) = 0;
 };
 }  // namespace ipfs::ctx
 

library/include/ipfs_client/ctx/null_cbor_parser.h

@@ -7,6 +7,8 @@ namespace ipfs::ctx {
  */
 class NullCborParser : public CborParser {
  public:
+  /*! @return NULL, always
+   */
   std::unique_ptr<DagCborValue> Parse(ByteView) override {
     return {};
   }

library/include/ipfs_client/gw/dnslink_requestor.h

@@ -12,7 +12,9 @@ namespace ipfs::gw {
  */
 class DnsLinkRequestor final : public Requestor {
  public:
-  explicit DnsLinkRequestor(std::shared_ptr<Client>);
+  /*! @param api The Client context API
+   */
+  explicit DnsLinkRequestor(std::shared_ptr<Client> api);
 
   HandleOutcome handle(RequestPtr) override;
   std::string_view name() const override;

library/include/ipfs_client/gw/gateway_request.h

@@ -38,6 +38,8 @@ constexpr std::size_t CAR_RESPONSE_BUFFER_SIZE = 5UL * 1024UL * 1024UL;
  */
 class GatewayRequest : public std::enable_shared_from_this<GatewayRequest> {
  public:
+  /*! Type for callbacks for when bytes are received
+   */
   using BytesReceivedHook =
       std::function<void(std::string_view, ByteView, ipld::BlockSource const&)>;
 
@@ -79,6 +81,9 @@ class GatewayRequest : public std::enable_shared_from_this<GatewayRequest> {
   std::string debug_string() const;
   void orchestrator(std::shared_ptr<Partition> const&);
   bool cachable() const;
+
+  /*! @return The part of the path that functions as an origin (the second component)
+   */
   std::string_view root_component() const;
   void root_component(std::string_view);
 

library/include/ipfs_client/gw/inline_request_handler.h

@@ -10,7 +10,11 @@ namespace ipfs::gw {
  */
 class InlineRequestHandler final : public Requestor {
  public:
-  HandleOutcome handle(RequestPtr) override;
+  /*! @param request The request to try handling
+   *  @return DONE (after responding) if it was an inline request
+   *    NOT_HANDLED otherwise
+   */
+  HandleOutcome handle(RequestPtr request) override;
   std::string_view name() const override;
 };
 }  // namespace ipfs::gw

library/include/ipfs_client/gw/requestor.h

@@ -41,6 +41,9 @@ class Requestor : public std::enable_shared_from_this<Requestor> {
 
  public:
   using RequestPtr = ::ipfs::gw::RequestPtr;
+  /*! @return The requestor's name, for debugging.
+   *    Typically this is 1:1 with the concrete type.
+   */
   virtual std::string_view name() const = 0;
 
   virtual ~Requestor() noexcept {}

library/include/ipfs_client/gw/terminating_requestor.h

@@ -9,9 +9,8 @@ namespace ipfs::gw {
  */
 class TerminatingRequestor : public Requestor {
  public:
-  using HandleOutcome = Requestor::HandleOutcome;
   std::string_view name() const override;
-  HandleOutcome handle(RequestPtr) override;
+  Requestor::HandleOutcome handle(RequestPtr) override;
 };
 }  // namespace ipfs::gw
 

library/include/ipfs_client/ipld/block_source.h

@@ -10,6 +10,8 @@ namespace ipfs::ipld {
 /*! Description of where a particular block was fetched from, for diagnostics
  */
 struct BlockSource {
+  /*! Source of now(). Defines timestamp type.
+   */
   using Clock = std::chrono::system_clock;
 
   /*! Categorization of sources

library/include/ipfs_client/ipld/dag_headers.h

@@ -14,6 +14,9 @@ class DagHeaders {
  public:
   void Add(BlockSource const&);
   void Finish();
+
+  /*! A list of HTTP header names and values
+   */
   using HeaderList = std::vector<std::pair<std::string, std::string>>;
 
   HeaderList const& headers() const { return headers_; }

library/include/ipfs_client/ipld/dag_node.h

@@ -73,6 +73,9 @@ class DagNode : public std::enable_shared_from_this<DagNode> {
   virtual ResolveResult resolve(ResolutionState& params) = 0;
 
  protected:
+  /*! The child nodes of this node, possibly not yet fetched.
+   *  @note In some cases the string is empty. For example as stem node of a UnixFS (multi-node) file.
+   */
   std::vector<std::pair<std::string, Link>> links_;
   std::shared_ptr<Client> api_;
 
@@ -147,7 +150,10 @@ class DagNode : public std::enable_shared_from_this<DagNode> {
    */
   virtual bool PreferOver(DagNode const& another) const;
 
-  void set_api(std::shared_ptr<Client>);
+  /*! Provide the Client API to be used in DAG operations
+   *  @param api Shared pointer to API for the context being run in
+   */
+  void set_api(std::shared_ptr<Client> api);
   void source(BlockSource src) { source_ = src; }
 };
 }  // namespace ipfs::ipld

library/include/ipfs_client/ipld/link.h

@@ -19,7 +19,7 @@ class Link {
   Ptr node;
 
   /*! Construct an unresolved IPLD link
-   *  @param The child's CID
+   *  @param cid The child's CID
    */
   explicit Link(std::string cid);
   /*! Construct a resolved IPLD link

library/include/ipfs_client/ipld/resolution_state.h

@@ -25,7 +25,14 @@ class ResolutionState {
   BlockLookup get_available_block;
 
  public:
-  ResolutionState(SlashDelimited path_to_resolve, ResponseSemantic, BlockLookup);
+  /*! Construct from starting info
+   *  @param path_to_resolve Relative to the node resolve is being called on
+   *  @param semantic If the resolution results in a stem, i.e. a directory-like not a file,
+   *    would the preference be for a listing preview HTML page -OR-
+   *    JSON that describes the links to files and CIDs to merge in with this JSON (in the case of a sharded dir)
+   *  @param lookup Functor that returns a pointer to a node for a given CID if it's already availabe, nullptr otherwise.
+   */
+  ResolutionState(SlashDelimited path_to_resolve, ResponseSemantic semantic, BlockLookup lookup);
 
   SlashDelimited MyPath() const;
   SlashDelimited PathToResolve() const;

library/include/ipfs_client/ipns_record.h

@@ -54,7 +54,9 @@ struct ValidatedIpns {
   std::string gateway_source;  ///< Who gave us this record?
 
   ValidatedIpns();  ///< Create an invalid default object
-  explicit ValidatedIpns(IpnsCborEntry const&);
+  /*! @param entry IPNS entry known to be valid
+   */
+  explicit ValidatedIpns(IpnsCborEntry const& entry);
   ValidatedIpns(ValidatedIpns&&);
   ValidatedIpns(ValidatedIpns const&);
   ValidatedIpns& operator=(ValidatedIpns const&);

library/include/ipfs_client/multi_base.h

@@ -42,7 +42,7 @@ struct Codec {
    *  Should match the name found in the multibase table.
    */
   std::string_view const name;
-  /*! @param Struct with the above fields filled
+  /*! @return Struct with the above fields filled
    *  @param code The multibase to fetch
    */
   static Codec const* Get(Code code);

library/include/ipfs_client/partition.h

@@ -17,8 +17,6 @@ class Client;
  */
 class Partition : public std::enable_shared_from_this<Partition> {
  public:
-  using GatewayAccess =
-      std::function<void(std::shared_ptr<gw::GatewayRequest>)>;
   using MimeDetection = std::function<
       std::string(std::string, std::string_view, std::string const&)>;
   void build_response(std::shared_ptr<IpfsRequest>);

library/include/ipfs_client/pb_dag.h

@@ -38,6 +38,10 @@ class PbDag {
    *    It's just a container of arbitrary bytes.
    */
   PbDag(Cid const& cid, ByteView bytes);
+  /*! Convenience constructor
+   *  @param cid - The CID of the block
+   *  @param bytes - The block
+   */
   PbDag(Cid const& cid, std::string_view bytes);
 
   PbDag(PbDag const&);

library/include/ipfs_client/response.h

@@ -24,6 +24,9 @@ struct Response {
   static Response PLAIN_NOT_FOUND;
   static Response IMMUTABLY_GONE;
   static Response HOST_NOT_FOUND_RESPONSE;
+  /*! @param body HTML text (the response of the body, not the `<body>`
+   *  @param location The Location header
+   */
   static Response html(std::string_view body, std::string_view location = {});
 };
 

library/include/vocab/raw_ptr.h

@@ -37,6 +37,8 @@ class raw_ptr {
   // construct. Set it to nullptr. We have time needed to read_start a word.
   raw_ptr() = delete;
 
+  /*! @param p Primitive raw pointer
+   */
   raw_ptr(T* p) : ptr_{p} {}
   raw_ptr(raw_ptr&&) = default;
   raw_ptr(raw_ptr const&) = default;

library/include/vocab/slash_delimited.h

@@ -17,6 +17,8 @@ struct SlashDelimited {
 
  public:
   SlashDelimited() : remainder_{""} {}
+  /*! @param unowned Text to parse into /-delimited components
+   */
   explicit SlashDelimited(std::string_view unowned);
   explicit operator bool() const;
   std::string_view pop();

library/src/ipfs_client/gw/gateway_state.h

@@ -38,7 +38,11 @@ class GatewayState {
   ctx::GatewayConfig const& cfg() const;
 
  public:
-  GatewayState(std::string_view prefix, std::shared_ptr<Client>);
+  /*! @param prefix The URL prefix that goes in front of HTTP requests to the gateway
+   *    e.g. https://ipfs.io/
+   *  @param api Access to the functionality of this client's context
+   */
+  GatewayState(std::string_view prefix, std::shared_ptr<Client> api);
   long score(GatewayRequest const&, unsigned) const;
   bool bored() const;
   bool over_rate();

library/src/ipfs_client/gw/multi_gateway_requestor.h

@@ -31,6 +31,8 @@ class MultiGatewayRequestor : public Requestor {
   void Next();
 
  public:
+  /*! @return "multi-gateway requestor"
+   */
   std::string_view name() const override;
   HandleOutcome handle(RequestPtr) override;
 };

library/src/ipfs_client/ipld/chunk.h

@@ -16,7 +16,10 @@ class Chunk : public DagNode {
   ResolveResult resolve(ResolutionState&) override;
 
  public:
-  explicit Chunk(std::string);
+  /*! Construct
+   *  @param bytes The blob itself
+   */
+  explicit Chunk(std::string bytes);
   ~Chunk() noexcept override;
 };
 }  // namespace ipfs::ipld

library/src/ipfs_client/ipld/dag_cbor_node.h

@@ -12,6 +12,8 @@ class DagCborNode final : public DagNode {
   ResolveResult resolve(ResolutionState&) override;
 
  public:
+  /*! The dict or document being represented
+   */
   using Data = DagCborValue;
   explicit DagCborNode(std::unique_ptr<Data>);
   ~DagCborNode() noexcept override;

library/src/ipfs_client/ipld/directory_shard.h

@@ -4,6 +4,8 @@
 #include <ipfs_client/ipld/dag_node.h>
 
 namespace ipfs::ipld {
+/*! A node in a sharded (HAMT) directory
+ */
 class DirShard : public DagNode {
   std::uint64_t const fanout_;
 
@@ -21,6 +23,7 @@ class DirShard : public DagNode {
 
  public:
   /*! Construct with a known fanout
+   *  @param fanout The number of buckets
    */
   explicit DirShard(std::uint64_t fanout = 256UL);
   ~DirShard() noexcept override;

library/src/ipfs_client/ipld/root.h

@@ -7,6 +7,9 @@
 #include <optional>
 
 namespace ipfs::ipld {
+/*! Since some operations will behave differently if a given node is being treated as
+   *    a DAG root, this proxy wraps around a node to give it those properties
+   */
 class Root : public DagNode {
   std::optional<redirects::File> redirects_;
 
@@ -16,7 +19,10 @@ class Root : public DagNode {
   bool expired() const override;
 
  public:
-  explicit Root(std::shared_ptr<DagNode>);
+  /*! Construct
+   *  @param node The actual node being treated as a DAG root
+   */
+  explicit Root(std::shared_ptr<DagNode> node);
   ~Root() noexcept override;
 };
 }  // namespace ipfs::ipld

library/src/ipfs_client/ipld/symlink.h

@@ -12,6 +12,12 @@ class Symlink : public DagNode {
   bool is_absolute() const;
 
  public:
+  /*! Construct from the text of the target
+   *  @target Either a path relative to this node's,
+   *    OR /an/absolute/path which is relative to the DAG root
+   *  @note If it points outside the DAG it'll be considered broken.
+   *    This can be achieved by simply using too many ../../..
+   */
   explicit Symlink(std::string target);
   ~Symlink() noexcept override;
 };

library/src/ipfs_client/redirects.h

@@ -17,7 +17,11 @@ class Directive {
   int const status_;
 
  public:
-  Directive(std::string_view, std::string_view, int);
+  /*! @param from path/glob to match against
+   *  @param to partial path to replace from with
+   *  @param status HTTP status to use in successful response that hit this rule
+   */
+  Directive(std::string_view from, std::string_view to, int status);
   std::uint16_t rewrite(std::string&) const;
   std::string error() const;
   bool valid() const { return error().empty(); }