Comment and improve coral::fs file walking interface

source/coral/files.cpp

@@ -144,23 +144,47 @@ export namespace coral {
 	 * Platform-generalized file system interface.
 	 */
 	struct fs {
-		using walker = closure<expected<optional<path>, io_error>()>;
+		/**
+		 * Errors that may occur while trying to walk a file tree.
+		 *
+		 * [walk_error::end_of_walk] reports that there are no more paths left in the file tree that to traverse.
+		 *
+		 * [walk_error::io_unavailable] indicates that an implementation-defined I/O error has occured during traversal
+		 * of the file tree and failed to recover the next file tree path as a result.
+		 */
+		enum class walk_error {
+			end_of_walk,
+			io_unavailable,
+		};
+
+		/**
+		 * Supplier of file paths from a file tree walking context created by calling [walk_files].
+		 *
+		 * Each subsequent invocation will produce either a valid path in the file tree from `target_path` or a
+		 * [walk_error], with [walk_error::end_of_walk] signalling that there are no more paths left in the file tree to
+		 * traverse. See [walk_error] for more details on potential errors.
+		 */
+		using walker = closure<expected<path, walk_error>()>;
 
 		virtual ~fs() {};
 
 		/**
-		 *
-		 */
-		virtual void walk_files(path const & target_path, closure<void(walker const &)> const & then) {}
-
-		/**
-		 * Attempts to read the file in `target_path`, calling `then` if it was successfully opened for reading.
+		 * Attempts to read the file in `target_path`, calling `then` if it was successfully opened for reading and
+		 * passing the [file_reader] context along.
 		 */
 		virtual void read_file(path const & target_path, closure<void(file_reader &)> const & then) {}
 
+		/**
+		 * Attempts to walk the file tree from `target_path`, calling `then` if it was successfully opened for walking
+		 * and passing the [walker] context along.
+		 *
+		 * See [walker] for more information on how to use it to traverse the file tree.
+		 */
+		virtual void walk_files(path const & target_path, closure<void(walker const &)> const & then) {}
+
 		/**
 		 * Attempts to write the file in the file system located at `target_path`, calling `then` if it was successfully
-		 * opened for writing.
+		 * opened for writing and passing the [file_writer] context along.
 		 */
 		virtual void write_file(path const & target_path, closure<void(file_writer &)> const & then) {}
 	};