Be more detailed about PHPdoc coding standards

wouterj · wouterj · commit be70365fad1b · 2022-07-28T12:02:38.000+02:00
diff --git a/contributing/code/standards.rst b/contributing/code/standards.rst
@@ -150,6 +150,8 @@ Structure
 * Use ``return null;`` when a function explicitly returns ``null`` values and
   use ``return;`` when the function returns ``void`` values;
 
+* Do not add the ``void`` return type to methods in tests;
+
 * Use braces to indicate control structure body regardless of the number of
   statements it contains;
 
@@ -253,19 +255,28 @@ Service Naming Conventions
 Documentation
 ~~~~~~~~~~~~~
 
-* Add PHPDoc blocks for all classes, methods, and functions (though you may
-  be asked to remove PHPDoc that do not add value);
+* Add PHPDoc blocks for classes, methods, and functions only when they add
+  relevant information that does not duplicate the name, native type
+  declaration or context (e.g. ``instanceof`` checks);
+
+* Only use annotations and types defined in `the PHPDoc reference`_. In
+  order to improve types for static analysis, the following annotations are
+  also allowed:
+
+  * `Generics`_, with the exception of ``@template-covariant``.
+  * `Conditional return types`_ using the vendor-prefixed ``@psalm-return``;
+  * `Class constants`_;
+  * `Callable types`_;
 
 * Group annotations together so that annotations of the same type immediately
   follow each other, and annotations of a different type are separated by a
   single blank line;
 
-* Omit the ``@return`` tag if the method does not return anything;
-
-* The ``@package`` and ``@subpackage`` annotations are not used;
+* Omit the ``@return`` annotation if the method does not return anything;
 
-* Don't inline PHPDoc blocks, even when they contain just one tag (e.g. don't
-  put ``/** {@inheritdoc} */`` in a single line);
+* Don't use one-line PHPDoc blocks on classes, methods and functions, even
+  when they contain just one annotation (e.g. don't put ``/** {@inheritdoc} */``
+  in a single line);
 
 * When adding a new class or when making significant changes to an existing class,
   an ``@author`` tag with personal contact information may be added, or expanded.
@@ -291,3 +302,8 @@ License
 .. _`snake_case`: https://en.wikipedia.org/wiki/Snake_case
 .. _`constructor property promotion`: https://www.php.net/manual/en/language.oop5.decon.php#language.oop5.decon.constructor.promotion
 .. _`trailing comma`: https://wiki.php.net/rfc/trailing_comma_in_parameter_list
+.. _`the PHPDoc reference`: https://docs.phpdoc.org/3.0/guide/references/phpdoc/index.html
+.. _`Conditional return types`: https://psalm.dev/docs/annotating_code/type_syntax/conditional_types/
+.. _`Class constants`: https://psalm.dev/docs/annotating_code/type_syntax/value_types/#regular-class-constants
+.. _`Callable types`: https://psalm.dev/docs/annotating_code/type_syntax/callable_types/
+.. _`Generics`: https://psalm.dev/docs/annotating_code/templated_annotations/
