From f30dfa830435df91cc57f4415cc4fc7bc42e9e9b Mon Sep 17 00:00:00 2001 From: Guy Sartorelli Date: Mon, 29 Jan 2024 12:07:05 +1300 Subject: [PATCH] DOC Document PHPDoc as a PHP coding standard --- .../05_Coding_Conventions/01_PHP_Coding_Conventions.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/en/05_Contributing/05_Coding_Conventions/01_PHP_Coding_Conventions.md b/en/05_Contributing/05_Coding_Conventions/01_PHP_Coding_Conventions.md index 3eff55d0f..e87cb942f 100644 --- a/en/05_Contributing/05_Coding_Conventions/01_PHP_Coding_Conventions.md +++ b/en/05_Contributing/05_Coding_Conventions/01_PHP_Coding_Conventions.md @@ -157,6 +157,16 @@ Order code in classes in the following order: - If you do write raw SQL, use double quotes around table/column names and use parameterised queries, for example `->where(['"Score" > ?' => 50])`. - Use [ANSI SQL](https://en.wikipedia.org/wiki/SQL#Standardization) format. +## PHPDoc + +PHPDocs are not only useful when looking at the source code, but are also used in the API documentation at . + +- All [public API](/project_governance/public_api) should have a PHPDoc to describe its purpose. +- All `DataObject` and `Extension` subclasses should have `@method` annotations in their PHPDoc for relations (`has_one`, `has_many`, etc). + - Do not add the annotation if a real method is declared with the same name. + - Include the relevant `use` statements for all classes mentioned in the annotation + - Return types should include generics, e.g. `@method HasManyList Members()` + ## Other conventions - Prefer the identical `===` operator over the equality `==` operator for comparisons.