Add @method PHPDoc annotations for relations

[GuySartorelli]

Currently there are no @method annotations for most relations in the Silverstripe CMS codebase. This means there is nothing telling developers which methods they can call to get those lists of relations, let alone what the type of list and items are for those relations. Developers have to refer to the source code to see what relations exist, and for which classes.

We should add @method annotations for all relations added on classes. Member already has some of these as an example.

We should add these using an automated tool, and add a CI component to validate that they are present. That way, as new relations are added, we will see if we've forgotten to add the @method annotations through failed CI jobs, and be able to add them at the time the new relation is added.

Related

• Add generic typehints in PHPDoc silverstripe-framework#11066

Acceptance criteria

• @method annotations are added to class PHPDoc comments for all relations directly added on that class
  • This applies for all relations (has_one, has_many, many_many)
  • The return type for the method is correct for all @method annotations, including generics (e.g. ManyManyList<SiteTree> for a non-through type many_many to SiteTree, or Image for a has_one to Image)
• For relations added via extensions, the @method annotation is added to the extension class's PHPDoc
• Missing @method annotations are picked up by CI (e.g. using phpstan or psalm)
• Extra @method annotations that don't relate to anything on the class are picked up by CI (e.g. using phpstan or psalm)
• Update PHP Codding standards to mentioned @method annotation.

Notes

• Once this is merged, we should look at how the API documentation is rendering annotation and do a follow card if needed.
• https://github.com/silverleague/silverstripe-ideannotator is one tool that can be used to add the @method annotations automagically.

New issues created

• Validate @method docblock tag in CI #171

Code writer

• https://github.com/emteknetnz/silverstripe-docblock-writer

PRs

• MNT Update @methods on class docblocks silverstripe-framework#11092
• MNT Update @methods on class docblocks silverstripe-framework#11093
• MNT Update @methods on class docblocks cwp-agencyextensions#107
• MNT Update @methods on class docblocks cwp#335
• MNT Update @methods on class docblocks silverstripe-elemental#1125
• MNT Update @methods on class docblocks dnadesign/silverstripe-elemental-userforms#84
• MNT Update @methods on class docblocks silverstripe-assets#581
• MNT Update @methods on class docblocks silverstripe-blog#734
• MNT Update @methods on class docblocks silverstripe-cms#2909
• MNT Update @methods on class docblocks silverstripe-contentreview#217
• MNT Update @methods on class docblocks silverstripe-documentconverter#64
• MNT Update @methods on class docblocks silverstripe-elemental-fileblock#46
• MNT Update @methods on class docblocks silverstripe-externallinks#114
• MNT Update @methods on class docblocks silverstripe-ldap#65
• MNT Update @methods on class docblocks silverstripe-mfa#521
• MNT Update @methods on class docblocks silverstripe-session-manager#174
• MNT Update @methods on class docblocks silverstripe-sharedraftcontent#218
• MNT Update @methods on class docblocks silverstripe-siteconfig#150
• MNT Update @methods on class docblocks silverstripe-staticpublishqueue#180
• MNT Update @methods on class docblocks silverstripe-subsites#551
• MNT Update @methods on class docblocks silverstripe-taxonomy#99
• MNT Update @methods on class docblocks silverstripe-userforms#1257
• MNT Update @methods on class docblocks silverstripe-versioned#428
• MNT Update @methods on class docblocks symbiote/silverstripe-advancedworkflow#509
• MNT Update @methods on class docblocks symbiote/silverstripe-queuedjobs#413

[emteknetnz]

I've linked a PR for a new module, this will need to be merged before setting up the CI side of things

[emteknetnz]

Have added just one PR to framework for peer review for now, if this is OK will do all the other modules on sink

[GuySartorelli]

All linked PRs merged