Add generic typehints in PHPDoc

GuySartorelli commented 7 months ago

We should add PHPDoc typehints for generics where appropriate, to improve DX and type safety.

Potentially Handy Links

Don’t use phpstan/psalm prefixes (i.e. use @return and @param directly)
Don't use any conditional return types
Add generic typehints for all list implementations
Add generic typehints for injector get(), create(), and any other methods where it would be relevant for injector
- NOTE: Not for Injectable - i.e. DataObject::create() should just return static which it already does.
Add generic typehints for methods which return different objects based on a classname that's passed in
- e.g. GridFieldConfig::getComponentByType()
- e.g. SapphireTest::objFromFixture()
spend a little bit of time to see if there are other quick wins we can get by introducing generics.

These can be useful for static analysis testing (e.g. via phpstan or psalm) to validate return types are what you expect them to be - we should probably spin off a separate card to implement that. There's some devs internally who have experience with that.
Once this is merged, we should look at how the API documentation is rendering generics and do a follow card if needed. (see https://github.com/silverstripe/api.silverstripe.org/issues/115)

emteknetnz commented 5 months ago

I reviewed up to and including recipe-cms

emteknetnz commented 5 months ago

I reviewed up to and including login-forms