Open
Description
There are some minor inconsistencies between docblocks throughout the codebase, for example some using @inheritdoc
vs. {@inheritdoc}
. Going forward to make sure all docblocks are consistent, the following criteria should be met:
- All lines must not exceed a length of 120 characters and should not break onto a newline before that limit unless there is a compelling reason to do so
- All references to classes must use their FQCN with a preceding back slash, e.g.
\p810\MySQL\ConnectionInterface
- All references to classes must be enclosed in back ticks (
``
), except for those that denote a type as part of its schema, e.g.@param
et. al - All properties must contain an
@var
annotation noting the possible type(s) it represents, and may contain a description but should not unless it's considered crucial for understanding (preferably the name of the property or its usage should communicate intent) - All
@param
annotations must consist of a type, argument name, and short description - All methods must open with a short description
- All methods must have an
@return
annotation - All methods that raise an exception (either directly or indirectly, i.e. through another called function) must contain an
@throws
annotation with the FQCN of the exception it raises and a short description of why - All instances of the
@inheritdoc
annotation must be wrapped in curly braces - There must be only one space between segments of any repeating annotation such as
@param
or@type
, and they must not be aligned in a tabular format - If an annotation's short description must span onto a newline, the first character of the newline must be spaced out so as to align with the first character of the description
- All special annotations e.g.
@psalm-suppress
or@codeCoverageIgnore
must precede a method or property's usual annotations - All annotations that denote an array must specify the array's type by Psalm's standard if possible, in lieu of the all encompassing
array
[1]
[1] For example, if you know that a property that is an array will always map a string
key to an instance of \p810\MySQL\Builder\Grammar\Expression
then you would use array<string, \p810\MySQL\Builder\Grammar\Expression>
.