docs: Fix UploadVerifyUpload/UploadStashFile hook docs

1. FSFile::getPropsFromPath() is not used by any code any more.
https://codesearch.wmflabs.org/search/?q=FSFile%3A%3AgetPropsFromPath&i=1
The only remaining usage is in one test. We might as well remove the
function.

2. The $props array is passed to the hook for convenience, in case all
the file properties are already available. Fetching them from a file on
disc can be an expensive operation, and should be avoided if the
information is already available. But the caller does not guarantee this
is set. Other callees already know this can be a falsy value, notably
LocalFile::upload().

Change-Id: I43724d18467b6fb68a963b2206332cf553c81b2c

diff --git a/docs/hooks.txt b/docs/hooks.txt
index 1419d0a..7f8b192 100644 (file)
--- a/docs/hooks.txt
+++ b/docs/hooks.txt
@@ -3568,7 +3568,10 @@ hook. If your extension absolutely, positively must prevent some files from
 being uploaded, use UploadVerifyFile or UploadVerifyUpload.
 $upload: (object) An instance of UploadBase, with all info about the upload
 $user: (object) An instance of User, the user uploading this file
-$props: (array) File properties, as returned by FSFile::getPropsFromPath()
+$props: (array|null) File properties, as returned by
+  MWFileProps::getPropsFromPath(). Note this is not always guaranteed to be set,
+  e.g. in test scenarios. Call MWFileProps::getPropsFromPath() yourself in case
+  you need the information.
 &$error: output: If the file stashing should be prevented, set this to the
   reason in the form of [ messagename, param1, param2, ... ] or a
   MessageSpecifier instance (you might want to use ApiMessage to provide machine
@@ -3597,7 +3600,10 @@ MIME type (same as UploadVerifyFile) and the information entered by the user
 (upload comment, file page contents etc.).
 $upload: (object) An instance of UploadBase, with all info about the upload
 $user: (object) An instance of User, the user uploading this file
-$props: (array) File properties, as returned by FSFile::getPropsFromPath()
+$props: (array|null) File properties, as returned by
+  MWFileProps::getPropsFromPath(). Note this is not always guaranteed to be set,
+  e.g. in test scenarios. Call MWFileProps::getPropsFromPath() yourself in case
+  you need the information.
 $comment: (string) Upload log comment (also used as edit summary)
 $pageText: (string) File description page text (only used for new uploads)
 &$error: output: If the file upload should be prevented, set this to the reason