Skip to content

Ensure consistent formatting for docblocks #8

Open
@p810

Description

@p810

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>.

Metadata

Metadata

Assignees

No one assigned

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions