-
Notifications
You must be signed in to change notification settings - Fork 0
Open
Labels
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.@paramet. al - All properties must contain an
@varannotation 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
@paramannotations must consist of a type, argument name, and short description - All methods must open with a short description
- All methods must have an
@returnannotation - All methods that raise an exception (either directly or indirectly, i.e. through another called function) must contain an
@throwsannotation with the FQCN of the exception it raises and a short description of why - All instances of the
@inheritdocannotation must be wrapped in curly braces - There must be only one space between segments of any repeating annotation such as
@paramor@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-suppressor@codeCoverageIgnoremust 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>.