DOC Document the file usage table

[emteknetnz]

Issue: silverstripe/silverstripe-admin#1098

Blocked by silverstripe/silverstripe-admin#1139

[Cheddam]

It feels like this could use some fleshing out - not having been across this API's development, I don't get a clear understanding of how I should be interacting with it from reading this doc.

• Would it make more sense to break out each of the available extension points and fully describe its purpose, behaviour, and any potential pitfalls? Performance implications seem particular important - updateUsageDataObject() in looks like it operates on every single DataObject in the table, which could get heavy very easily. Some of the methods could probably benefit from multiple example implementations, too.
• Are there any other sections of the documentation that could include links to this doc to make it more discoverable?
• Please reformat to a max of 120 characters per line
• An intro to this API needs to be included in the 4.7.0 / 4.7.0-beta1 changelog. In particular it'd be good to outline what change in behaviour developers will see from the Used On table when upgrading.

[emteknetnz]

@Cheddam

• I've added inline comments to the the extension hook examples to further elaborate what each of the extension hooks do
• I've reformatted to 120 chars
• I've added an intro in the beta changelog
• Rebased and retargeted to 4.7

I don't know where else in the docs it would make sense to link to this. It will have its own section in https://docs.silverstripe.org/en/4/developer_guides/files/#files which seems like it's good enough?

[emteknetnz]

@brynwhyman have implemented your feedback and add you as a co-author to the commit message

[Cheddam]

@emteknetnz Two more minor things - the changelog item needs to be added to the table of contents at the top of the doc, and you should replicate this item in the (provisional) 4.7.0 stable changelog for consistency.

In terms of where else in the docs this could be linked from, a note about it in the relationships article might make sense, since some of the examples there use Files:
https://docs.silverstripe.org/en/4/developer_guides/model/relations/

Stale