Improve documentation to files API describing two-part update procedure

[SheaBelsky]

Expected behavior

When calling .upload, .updateFile, etc. on a list and attempting to upload a new file, the contents of the file should reflect automatically in the Admin UI.

Actual/Current behavior

The Admin UI does not get updated with the information from the updated file. It is necessary to instead update the document a second time with the output from the file storage handler.

I understand that not updating the Admin UI provides some degree of flexibility, especially with the upload method returning the response object from the file storage handler. However, this functionality is not documented anywhere.

The "Methods" section of this documentation page only lists a single parameter, err, as an argument to the callback function once model._.field.upload is called. I discovered the second parameter passed from the callback and was able to use it to update the document manually.

It would be helpful for these two documentation changes to be made:

• Document the second parameter to the callback to model._.field.upload
• Document the fact that developers need to manually update the document with information from the file storage handler, and that this is not done automatically. The only time it happens automatically is if a file is uploaded through the Admin UI.

Steps to reproduce the actual/current behavior

asyncWaterfall([
    (cb) => {
        const allowedTypes = ["application/pdf", "image/png", "image/jpg", "image/jpeg"];
        const { customMap } = req.files;
        if (typeof customMap === "object" && allowedTypes.indexOf(customMap.mimetype) !== -1) {
            // Valid file
            const fileExtension = customMap.mimetype.split("/")[1];
            customMap.filename = `${locals.competition.key}_map.${fileExtension}`;
            customMap.name = customMap.filename;
            // This call to the underscore method only uploads the file through the file storage handler, and does not update the Admin UI
            return locals.competition._.venueMap.upload(customMap, cb);
        }
        else {
          return cb("Please specify a valid file for your tournament map.");
        }
    },
    (uploadData, cb) => {
        // The document needs to be manually updated with the information from the file storage handler
        locals.competition.venueMap = uploadData;
        locals.competition.save(cb);
    }
], (err) => {
    //.......
});

Environment

Software	Version
Keystone	4.0.0
Node.js	9.1.1
Browser	72.0.3626.109

[SheaBelsky]

I can provide a pull request to amend this, but I've been fighting with the "Edit this Page" link in the documentation not consistently working. I'm writing a second issue for that, and would like to also submit a PR to fix that too.

[SheaBelsky]

Looks the docs issue regarding 404s was pointed out in #4707, and is getting fixed in ghbolivar@8313dfa.