Streamline the existing PHPDoc comments

src/CSSList/AtRuleBlockList.php

@@ -6,7 +6,7 @@
 use Sabberworm\CSS\Property\AtRule;
 
 /**
- * A BlockList constructed by an unknown @-rule. @media rules are rendered into AtRuleBlockList objects.
+ * A BlockList constructed by an unknown at-rule. @media rules are rendered into AtRuleBlockList objects.
  */
 class AtRuleBlockList extends CSSBlockList implements AtRule
 {

src/CSSList/CSSList.php

@@ -23,7 +23,7 @@
 
 /**
  * A CSSList is the most generic container available. Its contents include RuleSet as well as other CSSList objects.
- * Also, it may contain Import and Charset objects stemming from @-rules.
+ * Also, it may contain Import and Charset objects stemming from at-rules.
  */
 abstract class CSSList implements Renderable, Commentable
 {
@@ -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/CSSList/Document.php

@@ -8,7 +8,7 @@
 
 /**
  * The root CSSList of a parsed file. Contains all top-level css contents, mostly declaration blocks,
- * but also any @-rules encountered.
+ * but also any at-rules encountered.
  */
 class Document extends CSSBlockList
 {

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 at-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 = '/
 	^(
 		(?:

src/Rule/Rule.php

@@ -128,7 +128,7 @@ public function setValue($mValue)
 
     /**
      * @deprecated Old-Style 2-dimensional array given. Retained for (some) backwards-compatibility.
-     *              Use setValue() instead and wrap the value inside a RuleValueList if necessary.
+     *             Use `setValue()` instead and wrap the value inside a RuleValueList if necessary.
      */
     public function setValues(array $aSpaceSeparatedValues)
     {
@@ -165,7 +165,7 @@ public function setValues(array $aSpaceSeparatedValues)
 
     /**
      * @deprecated Old-Style 2-dimensional array returned. Retained for (some) backwards-compatibility.
-     *              Use getValue() instead and check for the existance of a (nested set of) ValueList object(s).
+     *             Use `getValue()` instead and check for the existence of a (nested set of) ValueList object(s).
      */
     public function getValues()
     {

src/RuleSet/AtRuleSet.php

@@ -6,7 +6,7 @@
 use Sabberworm\CSS\Property\AtRule;
 
 /**
- * A RuleSet constructed by an unknown @-rule. @font-face rules are rendered into AtRuleSet objects.
+ * A RuleSet constructed by an unknown at-rule. `@font-face` rules are rendered into AtRuleSet objects.
  */
 class AtRuleSet extends RuleSet implements AtRule
 {

src/RuleSet/DeclarationBlock.php

@@ -102,7 +102,9 @@ public function setSelectors($mSelector, $oList = null)
         }
     }
 
-    // remove one of the selector of the block
+    /**
+     * Remove one of the selectors of the block.
+     */
     public function removeSelector($mSelector)
     {
         if ($mSelector instanceof Selector) {
@@ -118,15 +120,15 @@ public function removeSelector($mSelector)
     }
 
     /**
-     * @deprecated use getSelectors()
+     * @deprecated use `getSelectors()`
      */
     public function getSelector()
     {
         return $this->getSelectors();
     }
 
     /**
-     * @deprecated use setSelectors()
+     * @deprecated use `setSelectors()`
      */
     public function setSelector($mSelector, $oList = null)
     {
@@ -214,7 +216,7 @@ public function expandBorderShorthand()
                 } else {
                     if (in_array($mValue, $aBorderSizes)) {
                         $sNewRuleName = $sBorderRule . "-width";
-                    } else /* if(in_array($mValue, $aBorderStyles)) */ {
+                    } else {
                         $sNewRuleName = $sBorderRule . "-style";
                     }
                 }
@@ -287,7 +289,7 @@ public function expandDimensionsShorthand()
 
     /**
      * Convert shorthand font declarations
-     * (e.g. <tt>font: 300 italic 11px/14px verdana, helvetica, sans-serif;</tt>)
+     * (e.g. `font: 300 italic 11px/14px verdana, helvetica, sans-serif;`)
      * into their constituent parts.
      * */
     public function expandFontShorthand()
@@ -351,13 +353,13 @@ public function expandFontShorthand()
         $this->removeRule('font');
     }
 
-    /*
-     * Convert shorthand background declarations
-     * (e.g. <tt>background: url("chess.png") gray 50% repeat fixed;</tt>)
+    /**
+     * Converts shorthand background declarations
+     * (e.g. `background: url("chess.png") gray 50% repeat fixed;`)
      * into their constituent parts.
+     *
      * @see http://www.w3.org/TR/21/colors.html#propdef-background
-     * */
-
+     */
     public function expandBackgroundShorthand()
     {
         $aRules = $this->getRulesAssoc();
@@ -572,12 +574,11 @@ public function createBorderShorthand()
         $this->createShorthandProperties($aProperties, 'border');
     }
 
-    /*
+    /**
      * Looks for long format CSS dimensional properties
      * (margin, padding, border-color, border-style and border-width)
      * and converts them into shorthand CSS properties.
-     * */
-
+     */
     public function createDimensionsShorthand()
     {
         $aPositions = ['top', 'right', 'bottom', 'left'];
@@ -645,10 +646,11 @@ public function createDimensionsShorthand()
     }
 
     /**
-     * Looks for long format CSS font properties (e.g. <tt>font-weight</tt>) and
-     * tries to convert them into a shorthand CSS <tt>font</tt> property.
+     * Looks for long format CSS font properties (e.g. `font-weight`) and
+     * tries to convert them into a shorthand CSS `font` property.
+     *
      * At least font-size AND font-family must be present in order to create a shorthand declaration.
-     * */
+     */
     public function createFontShorthand()
     {
         $aFontProperties = [