From dfc89318ceddaa6801746f53c400cacb9685aabe Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Mon, 1 Nov 2021 17:09:52 +0200 Subject: [PATCH] Improve documentation of 'file-has-changed-p' * etc/NEWS: * doc/lispref/files.texi (File Attributes): Improve wording of the documentation of 'file-has-changed-p'. --- doc/lispref/files.texi | 14 ++++++++------ etc/NEWS | 4 ++-- 2 files changed, 10 insertions(+), 8 deletions(-) diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi index 250f7a3f9f5..b7420fc678f 100644 --- a/doc/lispref/files.texi +++ b/doc/lispref/files.texi @@ -1315,12 +1315,14 @@ on the 19th, @file{aug-20} was written on the 20th, and the file @end defun @defun file-has-changed-p filename -This convenience function is useful when, for instance, parsing files -run-time, and you typically want to re-read a file when it has -changed. This function returns non-@code{nil} the first time it's -called on @var{filename} in an Emacs session, but will return -@code{nil} on subsequent calls in that session (unless the file -changes its modification time). +This function returns non-@code{nil} if the time stamp of +@var{filename} has changed since the last call. When called for the +first time for some @var{filename}, it records the last modification +time of the file and returns non-@code{nil}. Thereafter, when called +for the same @var{filename}, it compares the current time stamp with +the recorded one and returns non-@code{nil} only if they are +different. This is useful when a Lisp program wants to re-read a file +whenever it changes. @end defun @defun file-attributes filename &optional id-format diff --git a/etc/NEWS b/etc/NEWS index 114441f1b6a..73f76076d46 100644 --- a/etc/NEWS +++ b/etc/NEWS @@ -369,8 +369,8 @@ Use 'exif-parse-file' and 'exif-field' instead. +++ *** New function 'file-has-changed-p'. This convenience function is useful when writing code that parses -files run-time, and allows you to easily re-parse files when they have -changed (but not otherwise). +files at run-time, and allows Lisp programs to re-parse files only +when they have changed. --- *** New function 'font-has-char-p'. -- 2.39.5