Apply changes requested during review.

Author: Vinai

guides/v2.1/coding-standards/docblock-standard-general.md

@@ -343,21 +343,19 @@ Functions and methods should have:
 
 * The declaration of all arguments (if any) using `@param` tag, unless the argument type is indicated in the method signature.
   All `@param` annotations must include the appropriate argument type.
-  If any argument requires a `@param` annotation, all arguments must be listed (all or none).
-* The `@param` annotations must be in the same order as the method arguments.
+  If any argument requires a `@param` annotation, all arguments must be listed (all or none).  
+  The `@param` annotations must be in the same order as the method arguments.
 * The declaration of the return type using the `@return` tag must only be added if the method return type signature
   does not supply all necessary information (see below for more information on return types).
 * Declaration of possibly thrown exception using `@throws` tag, if the actual body of function triggers throwing an exception.
-  All occurrences of `@throws` in a DocBlock must be after any `@param` and `@return` annotations.
+  All occurrences of `@throws` in a DocBlock must be after `@param` and `@return` annotations.
 
 **Exceptions to these rules:**
 
 * Testing methods in Unit tests may have doc blocks to describe the purpose of the test, for example referencing github issues.
 
 * Test method annotations may include data providers and other testing annotations.
 
-* Non-testing methods may have a doc block with description according to the rules above.
-
 #### Things to include
 
 * An explanation of input arguments and return values if it is not obvious from their name and type.
@@ -498,16 +496,36 @@ public function deleteDirectory($path)
 {:#return}
 
 In general method return type signatures should be prefered over `@return` type annotations.
-If that is not possible due to ambiguous return types, the `@return` type annotation must be used.
+If that is not possible due to ambiguous return types or because of backward compatibility constraints, the `@return` type annotation must be used.
 
-If there is no explicit return statement in a method or function or a return statement without a value, a `void` return type must be declared in the method signature.
+If there is no explicit return statement in a method or function or a return statement without a value, a `void` return type must be declared in the method signature. For example:
+
+```php
+function setName(string $name): void
+{
+   $this->name = $name;
+}
+```
+
+If the method returns itself, the method signature return type must be `self`. Here is an example:
+
+```php
+function withField(string $fieldName): self
+{
+   $this->fields[] = $fieldName;
+   return $this;
+}
+```
+
+If for backward compatibility reasons no return type can be added to the method signature, a `@return $this` annotation must be used.
 
-If the method returns itself, `@return $this` must be used, unless the return type is specified in the method signature.
 
 ### Constants
 {:#constants}
 
-Constants must have short description if they add information beyond what the constant name supplies.
+Constants may have a short description.
+If the short description adds no additional information beyond what the constant name already supplies, the
+short description must be omitted.
 
 For example, a global constant:
 
@@ -517,8 +535,11 @@ For example, a global constant:
  * Directory separator shorthand, intended to make code more readable.
  */
 define('DS', DIRECTORY_SEPARATOR);
+```
 
 Or constants in a class:
+
+```php
 class Profiler
 {
     /**