From 73298163010f6203e5a6c3359826a2fbe7a4b04b Mon Sep 17 00:00:00 2001
From: John Blackbourn <johnbillion@git.wordpress.org>
Date: Tue, 24 Oct 2017 22:49:13 +0000
Subject: [PATCH] Docs: Improve the docs for `validate_file()` and
 `validate_file_to_edit()`.

See #42016, #36170, #41017


git-svn-id: https://develop.svn.wordpress.org/trunk@42007 602fd350-edb4-49c9-b593-d223f7449a82
---
 src/wp-admin/includes/file.php |  8 ++++----
 src/wp-includes/functions.php  | 15 ++++++++-------
 2 files changed, 12 insertions(+), 11 deletions(-)

diff --git a/src/wp-admin/includes/file.php b/src/wp-admin/includes/file.php
index 83c91232e2..858f828185 100644
--- a/src/wp-admin/includes/file.php
+++ b/src/wp-admin/includes/file.php
@@ -653,14 +653,14 @@ function wp_tempnam( $filename = '', $dir = '' ) {
 }
 
 /**
- * Make sure that the file that was requested to edit, is allowed to be edited
+ * Makes sure that the file that was requested to be edited is allowed to be edited.
  *
- * Function will die if you are not allowed to edit the file
+ * Function will die if you are not allowed to edit the file.
  *
  * @since 1.5.0
  *
- * @param string $file file the users is attempting to edit
- * @param array $allowed_files Array of allowed files to edit, $file must match an entry exactly
+ * @param string $file          File the user is attempting to edit.
+ * @param array  $allowed_files Optional. Array of allowed files to edit, $file must match an entry exactly.
  * @return string|null
  */
 function validate_file_to_edit( $file, $allowed_files = '' ) {
diff --git a/src/wp-includes/functions.php b/src/wp-includes/functions.php
index 0962da02f8..a9c53d31e4 100644
--- a/src/wp-includes/functions.php
+++ b/src/wp-includes/functions.php
@@ -4238,17 +4238,18 @@ function iis7_supports_permalinks() {
 }
 
 /**
- * File validates against allowed set of defined rules.
+ * Validates a file name and path against an allowed set of rules.
  *
- * A return value of '1' means that the $file contains either '..' or './'. A
- * return value of '2' means that the $file contains ':' after the first
- * character. A return value of '3' means that the file is not in the allowed
- * files list.
+ * A return value of `1` means the file path contains directory traversal.
+ *
+ * A return value of `2` means the file path contains a Windows drive path.
+ *
+ * A return value of `3` means the file is not in the allowed files list.
  *
  * @since 1.2.0
  *
- * @param string $file File path.
- * @param array  $allowed_files List of allowed files.
+ * @param string $file          File path.
+ * @param array  $allowed_files Optional. List of allowed files.
  * @return int 0 means nothing is wrong, greater than 0 means something was wrong.
  */
 function validate_file( $file, $allowed_files = '' ) {