From 7cf1ba17645c6361d267f426c1ea50fa22557bd3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Basile=20Cl=C3=A9ment?= <129742207+bclement-ocp@users.noreply.github.com> Date: Fri, 26 May 2023 13:32:47 +0200 Subject: [PATCH] [doc] CCIO.File.walk This PR clarifies the behavior of `walk` and `read_dir ~recurse:true` by documenting that: - `walk p` always includes `p` - `read_dir ~recurse:true` only includes file paths (whereas `read_dir ~recurse:false` can include directory paths) --- src/core/CCIO.mli | 16 +++++++++++----- 1 file changed, 11 insertions(+), 5 deletions(-) diff --git a/src/core/CCIO.mli b/src/core/CCIO.mli index db58a1a3..14987928 100644 --- a/src/core/CCIO.mli +++ b/src/core/CCIO.mli @@ -229,7 +229,7 @@ module File : sig in the directory [d] (or an empty stream if [d] is not a directory). @raise Sys_error in case of error (e.g. permission denied). @param recurse if true (default [false]), sub-directories are also - explored. *) + explored, and the sequence only contains files. *) val read_exn : t -> string (** Read the content of the given file, or raises some exception. @@ -261,10 +261,16 @@ module File : sig type walk_item = [ `File | `Dir ] * t val walk : t -> walk_item gen - (** Like {!read_dir} (with [recurse=true]), this function walks - a directory recursively and yields either files or directories. - Is a file anything that doesn't satisfy {!is_directory} (including - symlinks, etc.) + (** [walk p] generates the files and directories contained in a directory + tree by walking the tree. {!walk} treats anything for which {!is_directory} + returns [false] (including symlinks, etc.) as a file. + + The argument is treated as part of its own directory tree, so the + result of [walk p] always includes [p]. + + This is similar to {!read_dir} with [recurse=True], except that {!read_dir} + with [recurse=True] only generates file entries. + @raise Sys_error in case of error (e.g. permission denied) during iteration. *) val walk_iter : t -> walk_item iter