jacobsantos
commented
9 years ago I believe others have already stated that such a recommendation won't be made in the PSR. The PSR isn't a standard guide for how to write phpDoc. This could made per project basis. I think the hardest part is not bikeshedding the standard and having devs reject it on the basis of arbitrary whitespace recommendation.
I usually use 2 spaces, but I do see how 4 spaces can appear better.
I will say that I would rather see the examples use some best practices, but for every person that uses a new line, one doesn't. For every one that uses 2 spaces to tab, there is one that doesn't and another that uses 4 or 6. If you took a survey, you would find enough projects that are members that probably don't use newlines.
mvriel
Fleshgrinder
This is actually something that I always wondered about and apparently many others do to, e.g. FriendsOfPHP/PHP-CS-Fixer#55.
Something that I often see in many projects (e.g. Symfony) is that people tend to align their stuff like this:
This is actually something I never understood, because it requires contributors to constantly realign the documentation. Additionally it does not really support readability to have everything align in a single line. In my projects I always put the description on the next line indented with two/four spaces (depending on the coding styles indent level) to avoid this and of course to highly increase readability (compare for yourself):
You might know already that I am a fan of consistency and reasoning, so we might find terms here to give a recommendation for people who are interested in such details. Note that this should only be a RECOMMENDED and not at all change anything in the definition of the PSR (well, maybe the formatting of the examples).
I also hope that we can start a discussion here without arguments like “but most people are doing this or that,” because I would prefer reasons that are really comprehensible.