Skip to content

Ensure consistent formatting for docblocks #8

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.

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

Open
p810 opened this issue Nov 12, 2019 · 0 comments
Open

Ensure consistent formatting for docblocks #8

p810 opened this issue Nov 12, 2019 · 0 comments

Comments

@p810
Copy link
Owner

p810 commented Nov 12, 2019

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

1 participant