From c5f1cdf055548338a52fe20ee65b86d0647969a2 Mon Sep 17 00:00:00 2001
From: Qyriad <qyriad@qyriad.me>
Date: Mon, 20 May 2024 13:16:09 -0600
Subject: [PATCH] add docstring to lookupFileArg

Change-Id: Ifc149764f5a15725d3d630677c6da29def4b0f3e
---
 src/libcmd/common-eval-args.hh | 22 +++++++++++++++++++++-
 1 file changed, 21 insertions(+), 1 deletion(-)

diff --git a/src/libcmd/common-eval-args.hh b/src/libcmd/common-eval-args.hh
index 6359b2579..08a4b65e4 100644
--- a/src/libcmd/common-eval-args.hh
+++ b/src/libcmd/common-eval-args.hh
@@ -28,6 +28,26 @@ private:
     std::map<std::string, std::string> autoArgs;
 };
 
-SourcePath lookupFileArg(EvalState & state, std::string_view s);
+/** @brief Resolve an argument that is generally a file, but could be something that
+ * is easy to resolve to a file, like a <lookup path> or a tarball URL.
+ *
+ * In particular, this will resolve and fetch pseudo-URLs starting with
+ * @c channel:, flakerefs starting with @c flake:, and anything that
+ * @ref nix::fetchers::downloadTarball() can take.
+ *
+ * Non-absolute files are looked up relative to the current directory(?)
+ * FIXME: the process's current directory or EvalState's current directory?
+ *
+ * @param state The nix::EvalState to base settings, store, and nixPath from.
+ *
+ * @param fileArg The the path-ish to resolve.
+ *
+ * @return A nix::SourcePath to the resolved and fetched file.
+ *
+ * @exception nix::FileTransferError from nix::fetchers::downloadTarball(). Probably others.
+ *
+ * @exception nix::ThrownError for failed search path lookup. Probably others.
+ */
+SourcePath lookupFileArg(EvalState & state, std::string_view fileArg);
 
 }