From 16cfba7759725fee4bdd4a4ab91d5a10e5a27d54 Mon Sep 17 00:00:00 2001 From: Wouter de Jong Date: Tue, 26 Jul 2022 16:08:33 +0200 Subject: [PATCH] Be more detailed about coding standards for PHPdoc --- contributing/code/standards.rst | 62 ++++++++++++++++++--------------- 1 file changed, 33 insertions(+), 29 deletions(-) diff --git a/contributing/code/standards.rst b/contributing/code/standards.rst index 5709a5184a6..e8af77af491 100644 --- a/contributing/code/standards.rst +++ b/contributing/code/standards.rst @@ -47,30 +47,27 @@ short example containing most features described below:: */ class FooBar { - const SOME_CONST = 42; + public const SOME_CONST = 42; /** * @var string */ private $fooBar; - private $qux; /** - * @param string $dummy Some argument description + * @param $dummy some argument description */ - public function __construct($dummy, Qux $qux) + public function __construct(string $dummy, Qux $qux) { $this->fooBar = $this->transformText($dummy); $this->qux = $qux; } /** - * @return string - * * @deprecated */ - public function someDeprecatedMethod() + public function someDeprecatedMethod(): string { trigger_deprecation('symfony/package-name', '5.1', 'The %s() method is deprecated, use Acme\Baz::someMethod() instead.', __METHOD__); @@ -80,14 +77,11 @@ short example containing most features described below:: /** * Transforms the input given as the first argument. * - * @param bool|string $dummy Some argument description - * @param array $options An options collection to be used within the transformation + * @param $options an options collection to be used within the transformation * - * @return string|null The transformed input - * - * @throws \RuntimeException When an invalid option is provided + * @throws \RuntimeException when an invalid option is provided */ - private function transformText($dummy, array $options = []) + private function transformText(bool|string $dummy, array $options = []): ?string { $defaultOptions = [ 'some_default' => 'values', @@ -100,16 +94,13 @@ short example containing most features described below:: } } - $mergedOptions = array_merge( - $defaultOptions, - $options - ); + $mergedOptions = array_merge($defaultOptions, $options); if (true === $dummy) { return 'something'; } - if (is_string($dummy)) { + if (\is_string($dummy)) { if ('values' === $mergedOptions['some_default']) { return substr($dummy, 0, 5); } @@ -122,11 +113,8 @@ short example containing most features described below:: /** * Performs some basic operations for a given value. - * - * @param mixed $value Some value to operate against - * @param bool $theSwitch Some switch to control the method's flow */ - private function performOperations($value = null, $theSwitch = false) + private function performOperations(mixed $value = null, bool $theSwitch = false) { if (!$theSwitch) { return; @@ -162,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; @@ -265,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. @@ -303,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/