From 48d3bd1ccac4f9ea8d081c0cda013757dd5f3d72 Mon Sep 17 00:00:00 2001
From: Max Kellermann <max.kellermann@gmail.com>
Date: Tue, 14 May 2024 19:41:34 +0200
Subject: [PATCH] lib/nfs/Connection: add API documentation

---
 src/lib/nfs/Connection.hxx | 49 ++++++++++++++++++++++++++++++++++++--
 1 file changed, 47 insertions(+), 2 deletions(-)

diff --git a/src/lib/nfs/Connection.hxx b/src/lib/nfs/Connection.hxx
index 66579e772..e01b1e206 100644
--- a/src/lib/nfs/Connection.hxx
+++ b/src/lib/nfs/Connection.hxx
@@ -159,29 +159,74 @@ public:
 	void AddLease(NfsLease &lease) noexcept;
 	void RemoveLease(NfsLease &lease) noexcept;
 
+	/**
+	 * Throws on error.
+	 */
 	void Stat(const char *path, NfsCallback &callback);
+
+	/**
+	 * Throws on error.
+	 */
 	void Lstat(const char *path, NfsCallback &callback);
 
+	/**
+	 * Throws on error.
+	 */
 	void OpenDirectory(const char *path, NfsCallback &callback);
+
+	/**
+	 * Read the next entry from the specified directory.
+	 *
+	 * Unlike the other I/O methods, this method blocks (because
+	 * libnfs has no non-blocking variant of nfs_readdir()) and
+	 * does not throw an exception on error.
+	 */
 	const struct nfsdirent *ReadDirectory(struct nfsdir *dir) noexcept;
+
+	/**
+	 * Close a directory handle returned by OpenDirectory().  This
+	 * method never blocks and never fails.
+	 */
 	void CloseDirectory(struct nfsdir *dir) noexcept;
 
 	/**
-	 * Throws std::runtime_error on error.
+	 * Throws on error.
 	 */
 	void Open(const char *path, int flags, NfsCallback &callback);
 
+	/**
+	 * Throws on error.
+	 */
 	void Stat(struct nfsfh *fh, NfsCallback &callback);
 
 	/**
-	 * Throws std::runtime_error on error.
+	 * Throws on error.
 	 */
 	void Read(struct nfsfh *fh, uint64_t offset, size_t size,
 		  NfsCallback &callback);
 
+	/**
+	 * Cancel the asynchronous operation associated with the
+	 * specified #NfsCallback.
+	 *
+	 * After this method returns, the caller may delete the
+	 * #NfsCallback.
+	 *
+	 * Not thread-safe.
+	 */
 	void Cancel(NfsCallback &callback) noexcept;
 
+	/**
+	 * Close the specified file handle asynchronously.
+	 *
+	 * Not thread-safe.
+	 */
 	void Close(struct nfsfh *fh) noexcept;
+
+	/**
+	 * Like Cancel(), but also close the specified NFS file
+	 * handle.
+	 */
 	void CancelAndClose(struct nfsfh *fh, NfsCallback &callback) noexcept;
 
 protected: