Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Be more detailed about coding standards for PHPdoc #17064

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jul 29, 2022
Merged

Be more detailed about coding standards for PHPdoc #17064

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
62 changes: 33 additions & 29 deletions contributing/code/standards.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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__);

Expand All @@ -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',
Expand All @@ -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);
}
Expand All @@ -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;
Expand Down Expand Up @@ -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;

Expand Down Expand Up @@ -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``.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why do we make that exception?

Copy link
Member Author

@wouterj wouterj Jul 26, 2022 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As far as I know, this is not (yet?) supported by PHPstan.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

phpstan supports it (otherwise, they would not have this blog post explaining it)

* `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.
Expand All @@ -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/