bug#73709: 29.4; Doc of `file-newer-than-file-p'

[Drew Adams via "Bug reports for GNU Emacs, the Swiss army knife of text editors" <bug-gnu-emacs@gnu.org>]

> > 1. Doc string suggestion, first line:
> >
> > "Return t if content of FILE1 is newer than content of FILE2."
> >
> > Short and clear.
> 
> It's short and clear, but it's inaccurate.  E.g., how to define
> "content newer" when both files have the same content (like if one of
> them is a copy of the other)?

That and other details should be available from
`file-attribute-modification-time', if important at
all (which is why it can be good to point to the doc
of that attribute).

But it's _not_ available even in that doc, is it?

 (elisp) `File Attributes':
 5. The time of last modification as a list of four integers
    (as above) ('file-attribute-modification-time').  This
    is the last time when the file's contents were modified.
                              ^^^^^^^^^^^^^^^
 Doc string of `file-attributes':
 5. Last modification time, likewise.  This is the
    time of the last change to the file's contents.
                                   ^^^^^^^^^^^^^^^

If we don't get into such detail in the doc for
the attribute then we certainly don't need to get
into it in the doc for `file-newer-than-file-p'.

But what's _most_ important here is to say WHAT
thing (aspect/attribute/dimension) it is whose
relative recentness is measured/compared.  Just
"newer" or "more recent" doesn't cut the mustard.

The thing that's measured/compared, as the attribute
doc itself says, is the "file's contents".  Don't
believe me; believe that doc.

As said before, it's a matter of _degree_ of clarity.
The current doc for the predicate isn't clear enough.
It misses what's most important - content changes.

  "IOW, you needn't go to the extreme of saying that
   we would need to explain everything in the doc of
   `file-newer-than-file-p'.  All that's needed for
   that doc is something a bit clearer than just saying
   that it's about a file's "newness".

You repeat that it's ALL OR NOTHING, claiming both (1)
the current doc is fine - clear enough and (2) anything
other than 100% complete information/clarity/details is
no better.  A false choice.

https://en.wikipedia.org/wiki/False_dilemma