Clarify what happens to match data on failure

Problem reported by Ernesto Alfonso (Bug#21279).
* doc/lispref/searching.texi (Regexp Search, Simple Match Data):
Document more carefully what happens to match data after a failed
search.
* src/search.c (Fmatch_beginning, Fmatch_end): Document that
the return value is undefined if the last search failed.
(Fmatch_data): Simplify doc string line 1.

1 files changed, 4 insertions, 3 deletions

diff --git a/doc/lispref/searching.texi b/doc/lispref/searching.texi
index 5a05c7c729d..60360cb98a9 100644
--- a/doc/lispref/searching.texi
+++ b/doc/lispref/searching.texi
@@ -1102,7 +1102,7 @@ For example,
 The index of the first character of the
 string is 0, the index of the second character is 1, and so on.
 
-After this function returns, the index of the first character beyond
+If this function finds a match, the index of the first character beyond
 the match is available as @code{(match-end 0)}.  @xref{Match Data}.
 
 @example
@@ -1425,8 +1425,9 @@ has no text properties.
 @end defun
 
 @defun match-beginning count
-This function returns the position of the start of the text matched by the
-last regular expression searched for, or a subexpression of it.
+If the last regular expression search found a match, this function
+returns the position of the start of the matching text or of a
+subexpression of it.
 
 If @var{count} is zero, then the value is the position of the start of
 the entire match.  Otherwise, @var{count} specifies a subexpression in