Merge pull request #8111 from obsidiansystems/improve-internal-api-docs

Convert a bunch of comments in headers to Doxygen documentation

1 files changed, 54 insertions, 18 deletions

diff --git a/src/libstore/content-address.hh b/src/libstore/content-address.hh
index f6a6f5140..634a51c38 100644
--- a/src/libstore/content-address.hh
+++ b/src/libstore/content-address.hh
@@ -5,44 +5,75 @@
 
 namespace nix {
 
+/**
+ * An enumeration of the ways we can serialize file system objects.
+ */
 enum struct FileIngestionMethod : uint8_t {
+    /**
+     * Flat-file hashing. Directly ingest the contents of a single file
+     */
     Flat = false,
+    /**
+     * Recursive (or NAR) hashing. Serializes the file-system object in Nix
+     * Archive format and ingest that
+     */
     Recursive = true
 };
 
+/**
+ * Somewhat obscure, used by \ref Derivation derivations and
+ * `builtins.toFile` currently.
+ */
 struct TextHash {
+    /**
+     * Hash of the contents of the text/file.
+     */
     Hash hash;
 };
 
-/// Pair of a hash, and how the file system was ingested
+/**
+ * For path computed by makeFixedOutputPath.
+ */
 struct FixedOutputHash {
+    /**
+     * How the file system objects are serialized
+     */
     FileIngestionMethod method;
+    /**
+     * Hash of that serialization
+     */
     Hash hash;
+
     std::string printMethodAlgo() const;
 };
 
-/*
-  We've accumulated several types of content-addressed paths over the years;
-  fixed-output derivations support multiple hash algorithms and serialisation
-  methods (flat file vs NAR). Thus, ‘ca’ has one of the following forms:
-
-  * ‘text:sha256:<sha256 hash of file contents>’: For paths
-    computed by makeTextPath() / addTextToStore().
-
-  * ‘fixed:<r?>:<ht>:<h>’: For paths computed by
-    makeFixedOutputPath() / addToStore().
-*/
+/**
+ * We've accumulated several types of content-addressed paths over the
+ * years; fixed-output derivations support multiple hash algorithms and
+ * serialisation methods (flat file vs NAR). Thus, ‘ca’ has one of the
+ * following forms:
+ *
+ * - ‘text:sha256:<sha256 hash of file contents>’: For paths
+ *   computed by Store::makeTextPath() / Store::addTextToStore().
+ *
+ * - ‘fixed:<r?>:<ht>:<h>’: For paths computed by
+ *   Store::makeFixedOutputPath() / Store::addToStore().
+ */
 typedef std::variant<
-    TextHash, // for paths computed by makeTextPath() / addTextToStore
-    FixedOutputHash // for path computed by makeFixedOutputPath
+    TextHash,
+    FixedOutputHash
 > ContentAddress;
 
-/* Compute the prefix to the hash algorithm which indicates how the files were
-   ingested. */
+/**
+ * Compute the prefix to the hash algorithm which indicates how the
+ * files were ingested.
+ */
 std::string makeFileIngestionPrefix(const FileIngestionMethod m);
 
-/* Compute the content-addressability assertion (ValidPathInfo::ca)
-   for paths created by makeFixedOutputPath() / addToStore(). */
+/**
+ * Compute the content-addressability assertion (ValidPathInfo::ca) for
+ * paths created by Store::makeFixedOutputPath() / Store::addToStore().
+ */
 std::string makeFixedOutputCA(FileIngestionMethod method, const Hash & hash);
 
 std::string renderContentAddress(ContentAddress ca);
@@ -65,6 +96,11 @@ struct FixedOutputHashMethod {
   HashType hashType;
 };
 
+/**
+ * Ways of content addressing but not a complete ContentAddress.
+ *
+ * A ContentAddress without a Hash.
+ */
 typedef std::variant<
     TextHashMethod,
     FixedOutputHashMethod