From 28c386422b5087aa13148cdef3db3433d06b72ad Mon Sep 17 00:00:00 2001
From: Markus Triska <triska@metalevel.at>
Date: Thu, 2 Jan 2025 18:54:27 +0100
Subject: [PATCH] state when the predicates are true

"returns" is not used in this way in logic programming. "return"
suggests that something went away and is now coming back, but this is
never the case in these situations. The arguments may be variables or
also fully known at the time of the call in most cases.
---
 src/lib/files.pl | 36 ++++++++++++++++++++----------------
 1 file changed, 20 insertions(+), 16 deletions(-)

diff --git a/src/lib/files.pl b/src/lib/files.pl
index 6c50aeebd..b8a6401f4 100644
--- a/src/lib/files.pl
+++ b/src/lib/files.pl
@@ -18,7 +18,7 @@
 */
 
 /* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-   Written 2020, 2022 by Markus Triska (triska@metalevel.at)
+   Written 2020-2025 by Markus Triska (triska@metalevel.at)
    Part of Scryer Prolog.
 
    Predicates for reasoning about files and directories.
@@ -89,17 +89,17 @@
 
 %% directory_files(+Directory, -Files).
 %
-% Returns the list of files *and* directories available at a specific
-% directory in the current system.
+% True if `Files` are the files *and* directories available at a specific
+% `Directory` in the current system.
 
 directory_files(Directory, Files) :-
         must_be(chars, Directory),
         can_be(list, Files),
         '$directory_files'(Directory, Files).
 
-%% file_size(+File, -Size).
+%% file_size(+File, ?Size).
 %
-% Returns the size (in bytes) of a file. The file must exist.
+% True iff `Size` is the size (in bytes) of `File`. The file must exist.
 
 file_size(File, Size) :-
         file_must_exist(File, file_size/2),
@@ -108,22 +108,25 @@
 
 %% file_exists(+File).
 %
-% Succeeds if File is a file that exists in the current system.
+% True iff `File` is a file that exists in the current system.
+
 file_exists(File) :-
         must_be(chars, File),
         '$file_exists'(File).
 
 %% directory_exists(+Directory).
 %
-% Succeeds if Directory is a directory that exists in the current system.
+% True iff `Directory` is a directory that exists in the current system.
+
 directory_exists(Directory) :-
         must_be(chars, Directory),
         '$directory_exists'(Directory).
 
 %% make_directory(+Directory).
 %
-% Succeeds if it creates a new directory named Directory in the current system.
+% Creates a new directory named `Directory`.
 % If you want to create a nested directory, use `make_directory_path/1`.
+
 make_directory(Directory) :-
         must_be(chars, Directory),
         '$make_directory'(Directory).
@@ -216,25 +219,26 @@
    For two time stamps A and B, if A precedes B, then A @< B holds.
 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - */
 
-%% file_modification_time(+File, -T).
+%% file_modification_time(+File, ?T).
 %
-% For a file File that must exist, it returns a time stamp  T with the modification time
+% For a file `File` that must exist, `T` is the modification time.
 %
-% T is a time stamp compatible with `library(time)`. 
+% T is a time stamp compatible with `library(time)`.
 file_modification_time(File, T) :-
         file_time_(File, modification, T).
 
-%% file_access_time(+File, -T).
+%% file_access_time(+File, ?T).
 %
-% For a file File that must exist, it returns a time stamp  T with the access time
+% For a file `File` that must exist, `T` is the access time.
 %
 % T is a time stamp compatible with `library(time)`.
+
 file_access_time(File, T) :-
         file_time_(File, access, T).
 
-%% file_creation_time(+File, -T).
+%% file_creation_time(+File, ?T).
 %
-% For a file File that must exist, it returns a time stamp  T with the creation time
+% For a file `File` that must exist, `T` is the creation time.
 %
 % T is a time stamp compatible with `library(time)`.
 file_creation_time(File, T) :-
@@ -246,7 +250,7 @@
         read_from_chars(T0, T).
 
 
-%% path_segments(Ps, Segments).
+%% path_segments(?Ps, ?Segments).
 %
 % True iff Segments are the segments of Ps.
 %