doc: input.hh

include/flox/input.hh

@@ -1,5 +1,8 @@
 /* ========================================================================== *
  *
+ * @file flox/input.hh
+ *
+ * @brief Declares objects used to process _flake reference_ URI inputs.
  *
  *
  * -------------------------------------------------------------------------- */
@@ -24,23 +27,34 @@ namespace flox {
 
 /* -------------------------------------------------------------------------- */
 
+/** A single _flake reference_ input to be resolved, locked, and scraped. */
 class Input {
 
   protected:
 
+    /**
+     * Locked flake reference containing the original, resolved, and locked
+     * forms of the reference provided by `nix'.
+     */
     std::shared_ptr<nix::flake::LockedFlake> _lockedFlake;
 
 
 /* -------------------------------------------------------------------------- */
 
   public:
 
+    /** Constructs an @a Input from a _flake reference_ URI string. */
     Input( std::string_view refURI );
+    /** Constructs an @a Input from a parsed _flake reference_ object. */
     Input( const resolve::FloxFlakeRef & ref );
 
 
 /* -------------------------------------------------------------------------- */
 
+    /**
+     * @return A unique hash fingerprint associated with the input's
+     *         locked flake.
+     */
       nix::Hash
     getFingerprint() const
     {
@@ -50,15 +64,30 @@ class Input {
 
 /* -------------------------------------------------------------------------- */
 
+    /**
+     * @return The set of defined flake output subtrees
+     *         ( "packages", "legacyPackages", "catalog" ) in the input's flake.
+     */
     virtual std::unordered_set<resolve::subtree_type> getSubtrees() = 0;
 
+    /**
+     * @param subtree The subtree ( @a resolve::subtree_type enum ) to
+     *                check for.
+     * @return `true` iff the input's flake outputs an attribute set
+     *         for @a subtree.
+     */
       virtual bool
     hasSubtree( const resolve::subtree_type & subtree )
     {
       const auto sts = this->getSubtrees();
       return sts.find( subtree ) != sts.cend();
     }
 
+    /**
+     * @param subtree The subtree ( string ) to check for.
+     * @return `true` iff the input's flake outputs an attribute set
+     *         for @a subtree.
+     */
       virtual bool
     hasSubtree( std::string_view subtree )
     {
@@ -68,16 +97,29 @@ class Input {
 
 /* -------------------------------------------------------------------------- */
 
+    /**
+     * @param subtree Subtree enum.
+     * @return The set of systems defined under flake output subtrees
+     *         ( "x86_64-linux", "aarch64-darwin", etc ) in the input's flake.
+     */
     virtual std::unordered_set<std::string_view> getSystems(
       const resolve::subtree_type & subtree
     ) = 0;
 
+    /**
+     * @param subtree Subtree name.
+     * @return The set of systems defined under flake output @a subtree
+     *         ( "x86_64-linux", "aarch64-darwin", etc ) in the input's flake.
+     */
       virtual std::unordered_set<std::string_view>
     getSystems( std::string_view subtree )
     {
       return this->getSystems( resolve::parseSubtreeType( subtree ) );
     }
 
+    /**
+     * @return `true` iff @a subtree outputs an attribute set under @a system.
+     */
       virtual bool
     hasSystem( const resolve::subtree_type & subtree, std::string_view system )
     {
@@ -86,6 +128,9 @@ class Input {
       return ss.find( system ) != ss.cend();
     }
 
+    /**
+     * @return `true` iff @a subtree outputs an attribute set under @a system.
+     */
       virtual bool
     hasSystem( std::string_view subtree, std::string_view system )
     {
@@ -95,12 +140,22 @@ class Input {
 
 /* -------------------------------------------------------------------------- */
 
+    /**
+     * @return The set of stabilities ( if any ) output by the `catalog` subtree
+     *         of the input's flake.
+     *         Flakes without a `catalog` subtree always return the empty set.
+     */
       virtual std::unordered_set<std::string_view>
     getStabilities( std::string_view system )
     {
       return {};
     }
 
+    /**
+     * @return The set of stabilities ( if any ) output by the `catalog` subtree
+     *         of the input's flake.
+     *         Flakes without a `catalog` subtree always return the empty set.
+     */
       virtual bool
     hasStability( std::string_view system, std::string_view stability )
     {
@@ -112,12 +167,33 @@ class Input {
 
 /* -------------------------------------------------------------------------- */
 
+    /** @return A list of package sets output by the input's flake. */
     virtual std::list<nix::ref<resolve::PackageSet>> getPackageSets() = 0;
+
+    /**
+     * @param subtree Subtree enum to get from.
+     * @param system  System pair such as "x86_64-linux" get.
+     * @return A pointer to a package set if it is output by the input's flake,
+     *         or `nullptr` if no such output exists.
+     */
     virtual std::shared_ptr<resolve::PackageSet>     getPackageSet(
       const resolve::subtree_type & subtree
     ,       std::string_view        system
     ) = 0;
 
+    /**
+     * @param subtreeOrSystem Subtree name ( "packages" or "legacyPackages" ) or
+     *                        system pair such as "x86_64-linux" get if
+     *                        attempting to get from the `catalog` subtree.
+     * @param systemOrCatalog  If @a subtreeOrSystem was either "packages" or
+     *                         "legacyPackages" then a system pair such as
+     *                         "x86_64-linux" to get.
+     *                         If @a subtreeOrSystem was a system pair then a
+     *                        `flox` catalog _stability_ name
+     *                        ( "stable", "staging", "unstable" ) to get from.
+     * @return A pointer to a package set if it is output by the input's flake,
+     *         or `nullptr` if no such output exists.
+     */
       virtual std::shared_ptr<resolve::PackageSet>
     getPackageSet( std::string_view subtreeOrSystem
                  , std::string_view systemOrCatalog