DOC Document PHPDoc as a PHP coding standard

[GuySartorelli]

Description

Documents the need for PHPDoc in general (which I was surprised was missing), and the need for @method annotations in particular.

Issues

• Validate @method docblock tag in CI .github#171

Pull request checklist

• The target branch is correct
  • See branches and commit messages
• All commits are relevant to the purpose of the PR (e.g. no TODO comments, unrelated rewording/restructuring, or arbitrary changes)
  • Small amounts of additional changes are usually okay, but if it makes it hard to concentrate on the relevant changes, ask for the unrelated changes to be reverted, and submitted as a separate PR.
• The commit messages follow our commit message guidelines
• The PR follows our contribution guidelines
• The changes follow our writing style guide
• Code examples follow our coding conventions
• CI is green

[emteknetnz]

Suggested change

- All [public API](/project_governance/public_api) should have a PHPDoc to describe its purpose.

We haven't agreed on this.

I don't really like this because if you have clear method names then the docblock description is a redundant duplication

I do notice the word "should" instead of "must", though then it's just kind of vague and it's not going to resolve any arguments

[GuySartorelli]

The word "must" doesn't appear anywhere in here - I think you're worrying a little too much about that word (or else this whole document is effectively pointless :p)

I've added extra criteria - if the api name and signature explain everything you need to know, then I guess we can leave a description off. But really, most of the time it should be added. I don't think this is controversial.

[emteknetnz]

Suggested change

	- All `DataObject` and `Extension` subclasses should have `@method` annotations in their PHPDoc for relations (`has_one`, `has_many`, etc).
	- All `DataObject` and `Extension` subclasses must have `@method` annotations in their PHPDoc for relations (`has_one`, `has_many`, etc).

Since it's being enforced by CI it's a must

[GuySartorelli]

The word "must" doesn't appear anywhere else in this document. Really it shouldn't matter whether these are enforce by CI or not. But I'll change this word since in this case yes, I suppose it would fail peer review (CI not-withstanding) if the annotation is missing.