Streamline the existing PHPDoc comments

Make them more useful for static code analysis, for human readers
and for rendering.

Author: oliverklee

src/CSSList/CSSList.php

@@ -180,7 +180,7 @@ private static function parseAtRule(ParserState $oParserState)
             }
             return new CSSNamespace($mUrl, $sPrefix, $iIdentifierLineNum);
         } else {
-            //Unknown other at rule (font-face or such)
+            // Unknown other at rule (font-face or such)
             $sArgs = trim($oParserState->consumeUntil('{', false, true));
             if (substr_count($sArgs, "(") != substr_count($sArgs, ")")) {
                 if ($oParserState->getSettings()->bLenientParsing) {
@@ -282,7 +282,7 @@ public function remove($oItemToRemove)
     /**
      * Replaces an item from the CSS list.
      *
-     * @param RuleSet|Import|Charset|CSSList $oItemToRemove
+     * @param RuleSet|Import|Charset|CSSList $oOldItem
      *        May be a RuleSet (most likely a DeclarationBlock), a Import, a Charset
      *        or another CSSList (most likely a MediaQuery)
      */

src/Comment/Comment.php

@@ -34,7 +34,7 @@ public function getLineNo()
     }
 
     /**
-     * @return string
+     * @param string $sComment
      */
     public function setComment($sComment)
     {

src/OutputFormat.php

@@ -11,18 +11,26 @@
 class OutputFormat
 {
     /**
-     * Value format
+     * Value format: `"` means double-quote, `'` means single-quote
+     *
+     * @var string
      */
-    // " means double-quote, ' means single-quote
     public $sStringQuotingType = '"';
 
-    // Output RGB colors in hash notation if possible
+    /**
+     * Output RGB colors in hash notation if possible
+     *
+     * @var string
+     */
     public $bRGBHashNotation = true;
 
     /**
      * Declaration format
+     *
+     * Semicolon after the last rule of a declaration block can be omitted. To do that, set this false.
+     *
+     * @var bool
      */
-    // Semicolon after the last rule of a declaration block can be omitted. To do that, set this false.
     public $bSemicolonAfterLastRule = true;
 
     /**
@@ -45,38 +53,57 @@ class OutputFormat
 
     public $sSpaceBetweenBlocks = "\n";
 
-    // Content injected in and around @-rule blocks.
+    /**
+     * Content injected in and around @-rule blocks.
+     *
+     * @var string
+     */
     public $sBeforeAtRuleBlock = '';
 
     public $sAfterAtRuleBlock = '';
 
-    // This is what’s printed before and after the comma if a declaration block contains multiple selectors.
+    /**
+     * This is what’s printed before and after the comma if a declaration block contains multiple selectors.
+     *
+     * @var string
+     */
     public $sSpaceBeforeSelectorSeparator = '';
 
     public $sSpaceAfterSelectorSeparator = ' ';
 
-    // This is what’s printed after the comma of value lists
+    /**
+     * This is what’s printed after the comma of value lists
+     *
+     * @var string
+     */
     public $sSpaceBeforeListArgumentSeparator = '';
 
     public $sSpaceAfterListArgumentSeparator = '';
 
     public $sSpaceBeforeOpeningBrace = ' ';
 
-    // Content injected in and around declaration blocks.
+    /**
+     * Content injected in and around declaration blocks.
+     *
+     * @var string
+     */
     public $sBeforeDeclarationBlock = '';
 
     public $sAfterDeclarationBlockSelectors = '';
 
     public $sAfterDeclarationBlock = '';
 
     /**
-     * Indentation
+     * Indentation character(s) per level. Only applicable if newlines are used in any of the spacing settings.
+     *
+     * @var string
      */
-    // Indentation character(s) per level. Only applicable if newlines are used in any of the spacing settings.
     public $sIndentation = "\t";
 
     /**
      * Output exceptions.
+     *
+     * @var bool
      */
     public $bIgnoreExceptions = false;
 

src/OutputFormatter.php

@@ -99,15 +99,15 @@ public function safely($cCode)
                 return $cCode();
             } catch (OutputException $e) {
                 return null;
-            } //Do nothing
+            } // Do nothing
         } else {
             // Run the code as-is
             return $cCode();
         }
     }
 
     /**
-     * Clone of the implode function but calls ->render with the current output format instead of ` __toString()
+     * Clone of the implode function but calls -> render with the current output format instead of `__toString()`
      */
     public function implode($sSeparator, array $aValues, $bIncreaseLevel = false)
     {

src/Parser.php

@@ -16,8 +16,7 @@ class Parser
     private $oParserState;
 
     /**
-     * Parser constructor.
-     * Note that that iLineNo starts from 1 and not 0
+     * Note that that iLineNo starts from 1 and not 0.
      *
      * @param $sText
      * @param Settings|null $oParserSettings

src/Parsing/ParserState.php

@@ -100,7 +100,7 @@ public function parseCharacter($bIsForIdentifier)
             }
             $sUnicode = $this->consumeExpression('/^[0-9a-fA-F]{1,6}/u', 6);
             if ($this->strlen($sUnicode) < 6) {
-                //Consume whitespace after incomplete unicode escape
+                // Consume whitespace after incomplete unicode escape
                 if (preg_match('/\\s/isSu', $this->peek())) {
                     if ($this->comes('\r\n')) {
                         $this->consume(2);

src/Property/AtRule.php

@@ -10,7 +10,7 @@ interface AtRule extends Renderable, Commentable
     // Since there are more set rules than block rules,
     // we’re whitelisting the block rules and have anything else be treated as a set rule.
     const BLOCK_RULES = 'media/document/supports/region-style/font-feature-values';
-    // …and more font-specific ones (to be used inside font-feature-values)
+    // … and more font-specific ones (to be used inside font-feature-values)
     const SET_RULES = 'font-face/counter-style/page/swash/styleset/annotation';
 
     /**

src/Property/Import.php

@@ -6,7 +6,7 @@
 use Sabberworm\CSS\Value\URL;
 
 /**
- * Class representing an @import rule.
+ * Class representing an `@import` rule.
  */
 class Import implements AtRule
 {

src/Property/KeyframeSelector.php

@@ -4,8 +4,11 @@
 
 class KeyframeSelector extends Selector
 {
-    //Regexes for specificity calculations
-
+    /**
+     * regexp for specificity calculations
+     *
+     * @var string
+     */
     const SELECTOR_VALIDATION_RX = '/
 	^(
 		(?:

src/Property/Selector.php

@@ -8,7 +8,11 @@
  */
 class Selector
 {
-    //Regexes for specificity calculations
+    /**
+     * regexp for specificity calculations
+     *
+     * @var string
+     */
     const NON_ID_ATTRIBUTES_AND_PSEUDO_CLASSES_RX = '/
 	(\.[\w]+)                   # classes
 	|
@@ -28,6 +32,11 @@ class Selector
 	))
 	/ix';
 
+    /**
+     * regexp for specificity calculations
+     *
+     * @var string
+     */
     const ELEMENTS_AND_PSEUDO_ELEMENTS_RX = '/
 	((^|[\s\+\>\~]+)[\w]+   # elements
 	|
@@ -36,6 +45,11 @@ class Selector
 	))
 	/ix';
 
+    /**
+     * regexp for specificity calculations
+     *
+     * @var string
+     */
     const SELECTOR_VALIDATION_RX = '/
 	^(
 		(?: