From 6c293a3d7f4ce3a06fbd881349d69d2e9a69284f Mon Sep 17 00:00:00 2001
From: Max Kellermann <max@musicpd.org>
Date: Tue, 10 Jan 2017 23:15:16 +0100
Subject: [PATCH] lib/nfs: add more API documentation

---
 src/lib/nfs/Callback.hxx   | 12 +++++++++++
 src/lib/nfs/FileReader.hxx | 43 ++++++++++++++++++++++++++++++++++++++
 2 files changed, 55 insertions(+)

diff --git a/src/lib/nfs/Callback.hxx b/src/lib/nfs/Callback.hxx
index a21d9e5d8..18bba6343 100644
--- a/src/lib/nfs/Callback.hxx
+++ b/src/lib/nfs/Callback.hxx
@@ -24,9 +24,21 @@
 
 #include <exception>
 
+/**
+ * Callbacks for an asynchronous libnfs operation.
+ *
+ * Note that no callback is invoked for cancelled operations.
+ */
 class NfsCallback {
 public:
+	/**
+	 * The operation completed successfully.
+	 */
 	virtual void OnNfsCallback(unsigned status, void *data) = 0;
+
+	/**
+	 * An error has occurred.
+	 */
 	virtual void OnNfsError(std::exception_ptr &&e) = 0;
 };
 
diff --git a/src/lib/nfs/FileReader.hxx b/src/lib/nfs/FileReader.hxx
index d43103cd0..911e62053 100644
--- a/src/lib/nfs/FileReader.hxx
+++ b/src/lib/nfs/FileReader.hxx
@@ -35,6 +35,14 @@
 struct nfsfh;
 class NfsConnection;
 
+/**
+ * A helper class which helps with reading from a file.  It obtains a
+ * connection lease (#NfsLease), opens the given file, "stats" the
+ * file, and finally allos you to read its contents.
+ *
+ * To get started, derive your class from it and implement the pure
+ * virtual methods, construct an instance, and call Open().
+ */
 class NfsFileReader : NfsLease, NfsCallback, DeferredMonitor {
 	enum class State {
 		INITIAL,
@@ -63,14 +71,30 @@ public:
 	void DeferClose();
 
 	/**
+	 * Open the file.  This method is thread-safe.
+	 *
 	 * Throws std::runtime_error on error.
 	 */
 	void Open(const char *uri);
 
 	/**
+	 * Attempt to read from the file.  This may only be done after
+	 * OnNfsFileOpen() has been called.  Only one read operation
+	 * may be performed at a time.
+	 *
+	 * This method is not thread-safe and must be called from
+	 * within the I/O thread.
+	 *
 	 * Throws std::runtime_error on error.
 	 */
 	void Read(uint64_t offset, size_t size);
+
+	/**
+	 * Cancel the most recent Read() call.
+	 *
+	 * This method is not thread-safe and must be called from
+	 * within the I/O thread.
+	 */
 	void CancelRead();
 
 	bool IsIdle() const {
@@ -78,8 +102,27 @@ public:
 	}
 
 protected:
+	/**
+	 * The file has been opened successfully.  It is a regular
+	 * file, and its size is known.  It is ready to be read from
+	 * using Read().
+	 *
+	 * This method will be called from within the I/O thread.
+	 */
 	virtual void OnNfsFileOpen(uint64_t size) = 0;
+
+	/**
+	 * A Read() has completed successfully.
+	 *
+	 * This method will be called from within the I/O thread.
+	 */
 	virtual void OnNfsFileRead(const void *data, size_t size) = 0;
+
+	/**
+	 * An error has occurred, which can be either while waiting
+	 * for OnNfsFileOpen(), or while waiting for OnNfsFileRead(),
+	 * or if disconnected while idle.
+	 */
 	virtual void OnNfsFileError(std::exception_ptr &&e) = 0;
 
 private: