add docstring to lookupFileArg

Change-Id: Ifc149764f5a15725d3d630677c6da29def4b0f3e

1 files changed, 21 insertions, 1 deletions

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);
 
 }