From 6a5c7709639579b6445177d93888b137d2fe18bb Mon Sep 17 00:00:00 2001
From: Oliver Klee <github@oliverklee.de>
Date: Sat, 3 Jul 2021 12:05:50 +0200
Subject: [PATCH] Sync the code documentation from the README to the source
 files

This should help readers understand the code.

Also drop outdated documentation and polish the existing prose.

Fixes #300
---
 README.md                        | 30 ++++++++++++++----------------
 src/CSSList/CSSList.php          |  8 +++++---
 src/CSSList/Document.php         | 13 +++++++------
 src/Parser.php                   |  8 +++++++-
 src/Parsing/ParserState.php      |  8 +++++++-
 src/Rule/Rule.php                |  5 +++--
 src/RuleSet/AtRuleSet.php        |  5 ++++-
 src/RuleSet/DeclarationBlock.php |  5 ++++-
 src/RuleSet/RuleSet.php          |  9 +++++++--
 src/Settings.php                 | 19 +++++++++++++++----
 src/Value/CSSFunction.php        |  4 ++++
 src/Value/CSSString.php          |  5 +++++
 src/Value/Color.php              |  4 ++++
 src/Value/RuleValueList.php      |  5 +++++
 src/Value/Size.php               |  3 +++
 src/Value/URL.php                |  3 +++
 src/Value/Value.php              |  4 ++++
 src/Value/ValueList.php          |  6 ++++++
 18 files changed, 107 insertions(+), 37 deletions(-)

diff --git a/README.md b/README.md
index 596b68d1..eb129637 100644
--- a/README.md
+++ b/README.md
@@ -33,7 +33,7 @@ The resulting CSS document structure can be manipulated prior to being output.
 
 #### Charset
 
-The charset option is used only if no `@charset` declaration is found in the CSS file. UTF-8 is the default, so you won’t have to create a settings object at all if you don’t intend to change that.
+The charset option will only be used if the CSS file does not contain an `@charset` declaration. UTF-8 is the default, so you won’t have to create a settings object at all if you don’t intend to change that.
 
 ```php
 $settings = \Sabberworm\CSS\Settings::create()
@@ -69,12 +69,9 @@ The resulting data structure consists mainly of five basic types: `CSSList`, `Ru
 
 #### CSSList
 
-`CSSList` represents a generic CSS container, most likely containing declaration blocks (rule sets with a selector), but it may also contain at-rules, charset declarations, etc. `CSSList` has the following concrete subtypes:
+`CSSList` represents a generic CSS container, most likely containing declaration blocks (rule sets with a selector), but it may also contain at-rules, charset declarations, etc.
 
-* `Document` – representing the root of a CSS file.
-* `MediaQuery` – represents a subsection of a `CSSList` that only applies to an output device matching the contained media query.
-
-To access the items stored in a `CSSList` – like the document you got back when calling `$parser->parse()` –, use `getContents()`, then iterate over that collection and use instanceof to check whether you’re dealing with another `CSSList`, a `RuleSet`, a `Import` or a `Charset`.
+To access the items stored in a `CSSList` – like the document you got back when calling `$parser->parse()` –, use `getContents()`, then iterate over that collection and use `instanceof` to check whether you’re dealing with another `CSSList`, a `RuleSet`, a `Import` or a `Charset`.
 
 To append a new item (selector, media query, etc.) to an existing `CSSList`, construct it using the constructor for this class and use the `append($oItem)` method.
 
@@ -82,16 +79,16 @@ To append a new item (selector, media query, etc.) to an existing `CSSList`, con
 
 `RuleSet` is a container for individual rules. The most common form of a rule set is one constrained by a selector. The following concrete subtypes exist:
 
-* `AtRuleSet` – for generic at-rules which do not match the ones specifically mentioned like `@import`, `@charset` or `@media`. A common example for this is `@font-face`.
+* `AtRuleSet` – for generic at-rules for generic at-rules which are not covered by specific classes, i.e., not `@import`, `@charset` or `@media`. A common example for this is `@font-face`.
 * `DeclarationBlock` – a `RuleSet` constrained by a `Selector`; contains an array of selector objects (comma-separated in the CSS) as well as the rules to be applied to the matching elements.
 
 Note: A `CSSList` can contain other `CSSList`s (and `Import`s as well as a `Charset`), while a `RuleSet` can only contain `Rule`s.
 
-If you want to manipulate a `RuleSet`, use the methods `addRule(Rule $rule)`, `getRules()` and `removeRule($rule)` (which accepts either a `Rule` instance or a rule name; optionally suffixed by a dash to remove all related rules).
+If you want to manipulate a `RuleSet`, use the methods `addRule(Rule $rule)`, `getRules()` and `removeRule($rule)` (which accepts either a `Rule` or a rule name; optionally suffixed by a dash to remove all related rules).
 
 #### Rule
 
-`Rule`s just have a key (the rule) and a value. These values are all instances of a `Value`.
+`Rule`s just have a string key (the rule) and a `Value`.
 
 #### Value
 
@@ -100,21 +97,22 @@ If you want to manipulate a `RuleSet`, use the methods `addRule(Rule $rule)`, `g
 * `Size` – consists of a numeric `size` value and a unit.
 * `Color` – colors can be input in the form #rrggbb, #rgb or schema(val1, val2, …) but are always stored as an array of ('s' => val1, 'c' => val2, 'h' => val3, …) and output in the second form.
 * `CSSString` – this is just a wrapper for quoted strings to distinguish them from keywords; always output with double quotes.
-* `URL` – URLs in CSS; always output in URL("") notation.
+* `URL` – URLs in CSS; always output in `URL("")` notation.
+
+There is another abstract subclass of `Value`, `ValueList`: A `ValueList` represents a lists of `Value`s, separated by some separation character (mostly `,`, whitespace, or `/`).
 
-There is another abstract subclass of `Value`, `ValueList`. A `ValueList` represents a lists of `Value`s, separated by some separation character (mostly `,`, whitespace, or `/`). There are two types of `ValueList`s:
+There are two types of `ValueList`s:
 
-* `RuleValueList` – The default type, used to represent all multi-valued rules like `font: bold 12px/3 Helvetica, Verdana, sans-serif;` (where the value would be a whitespace-separated list of the primitive value `bold`, a slash-separated list and a comma-separated list).
+* `RuleValueList` – The default type, used to represent all multivalued rules like `font: bold 12px/3 Helvetica, Verdana, sans-serif;` (where the value would be a whitespace-separated list of the primitive value `bold`, a slash-separated list and a comma-separated list).
 * `CSSFunction` – A special kind of value that also contains a function name and where the values are the function’s arguments. Also handles equals-sign-separated argument lists like `filter: alpha(opacity=90);`.
 
 #### Convenience methods
 
-There are a few convenience methods on Document to ease finding, manipulating and deleting rules:
+There are a few convenience methods on `Document` to ease finding, manipulating and deleting rules:
 
-* `getAllDeclarationBlocks()` – does what it says; no matter how deeply nested your selectors are. Aliased as `getAllSelectors()`.
-* `getAllRuleSets()` – does what it says; no matter how deeply nested your rule sets are.
+* `getAllDeclarationBlocks()` – does what it says; no matter how deeply nested the selectors are. Aliased as `getAllSelectors()`.
+* `getAllRuleSets()` – does what it says; no matter how deeply nested the rule sets are.
 * `getAllValues()` – finds all `Value` objects inside `Rule`s.
-* `getSelectorsBySpecificity(int: $specificity)` - finds all selectors with the requested specificity. `$specificity` is an integer with `1` being the highest specificity value. The method behaves just like  `getAllDeclarationBlocks()` if no parameter is passed.
 
 ## To-Do
 
diff --git a/src/CSSList/CSSList.php b/src/CSSList/CSSList.php
index 148cf19d..dcd8c331 100644
--- a/src/CSSList/CSSList.php
+++ b/src/CSSList/CSSList.php
@@ -24,10 +24,10 @@
 use Sabberworm\CSS\Value\Value;
 
 /**
- * A `CSSList` is the most generic container available. Its contents include `RuleSet` as well as other `CSSList`
- * objects.
+ * This is the most generic container available. It can contain `DeclarationBlock`s (rule sets with a selector),
+ * `RuleSet`s as well as other `CSSList` objects.
  *
- * Also, it may contain `Import` and `Charset` objects stemming from at-rules.
+ * It can also contain `Import` and `Charset` objects stemming from at-rules.
  */
 abstract class CSSList implements Renderable, Commentable
 {
@@ -444,6 +444,8 @@ protected function renderListContents(OutputFormat $oOutputFormat)
     abstract public function isRootList();
 
     /**
+     * Returns the stored items.
+     *
      * @return array<int, RuleSet|Import|Charset|CSSList>
      */
     public function getContents()
diff --git a/src/CSSList/Document.php b/src/CSSList/Document.php
index b2f50434..bad99831 100644
--- a/src/CSSList/Document.php
+++ b/src/CSSList/Document.php
@@ -11,8 +11,8 @@
 use Sabberworm\CSS\Value\Value;
 
 /**
- * The root `CSSList` of a parsed file. Contains all top-level CSS contents, mostly declaration blocks,
- * but also any at-rules encountered.
+ * This class represents the root of a parsed CSS file. It contains all top-level CSS contents: mostly declaration
+ * blocks, but also any at-rules encountered (`Import` and `Charset`).
  */
 class Document extends CSSBlockList
 {
@@ -37,7 +37,8 @@ public static function parse(ParserState $oParserState)
     }
 
     /**
-     * Gets all `DeclarationBlock` objects recursively.
+     * Gets all `DeclarationBlock` objects recursively, no matter how deeply nested the selectors are.
+     * Aliased as `getAllSelectors()`.
      *
      * @return array<int, DeclarationBlock>
      */
@@ -62,7 +63,7 @@ public function getAllSelectors()
     }
 
     /**
-     * Returns all `RuleSet` objects found recursively in the tree.
+     * Returns all `RuleSet` objects recursively found in the tree, no matter how deeply nested the rule sets are.
      *
      * @return array<int, RuleSet>
      */
@@ -75,7 +76,7 @@ public function getAllRuleSets()
     }
 
     /**
-     * Returns all `Value` objects found recursively in the tree.
+     * Returns all `Value` objects found recursively in `Rule`s in the tree.
      *
      * @param CSSList|RuleSet|string $mElement
      *        the `CSSList` or `RuleSet` to start the search from (defaults to the whole document).
@@ -102,7 +103,7 @@ public function getAllValues($mElement = null, $bSearchInFunctionArguments = fal
     }
 
     /**
-     * Returns all `Selector` objects found recursively in the tree.
+     * Returns all `Selector` objects with the requested specificity found recursively in the tree.
      *
      * Note that this does not yield the full `DeclarationBlock` that the selector belongs to
      * (and, currently, there is no way to get to that).
diff --git a/src/Parser.php b/src/Parser.php
index f3b0493a..e582cfab 100644
--- a/src/Parser.php
+++ b/src/Parser.php
@@ -17,7 +17,7 @@ class Parser
     private $oParserState;
 
     /**
-     * @param string $sText
+     * @param string $sText the complete CSS as text (i.e., usually the contents of a CSS file)
      * @param Settings|null $oParserSettings
      * @param int $iLineNo the line number (starting from 1, not from 0)
      */
@@ -30,6 +30,8 @@ public function __construct($sText, Settings $oParserSettings = null, $iLineNo =
     }
 
     /**
+     * Sets the charset to be used if the CSS does not contain an `@charset` declaration.
+     *
      * @param string $sCharset
      *
      * @return void
@@ -40,6 +42,8 @@ public function setCharset($sCharset)
     }
 
     /**
+     * Returns the charset that is used if the CSS does not contain an `@charset` declaration.
+     *
      * @return void
      */
     public function getCharset()
@@ -49,6 +53,8 @@ public function getCharset()
     }
 
     /**
+     * Parses the CSS provided to the constructor and creates a `Document` from it.
+     *
      * @return Document
      *
      * @throws SourceException
diff --git a/src/Parsing/ParserState.php b/src/Parsing/ParserState.php
index df18f557..633cfbe3 100644
--- a/src/Parsing/ParserState.php
+++ b/src/Parsing/ParserState.php
@@ -33,6 +33,8 @@ class ParserState
     private $iCurrentPosition;
 
     /**
+     * will only be used if the CSS does not contain an `@charset` declaration
+     *
      * @var string
      */
     private $sCharset;
@@ -48,7 +50,7 @@ class ParserState
     private $iLineNo;
 
     /**
-     * @param string $sText
+     * @param string $sText the complete CSS as text (i.e., usually the contents of a CSS file)
      * @param int $iLineNo
      */
     public function __construct($sText, Settings $oParserSettings, $iLineNo = 1)
@@ -61,6 +63,8 @@ public function __construct($sText, Settings $oParserSettings, $iLineNo = 1)
     }
 
     /**
+     * Sets the charset to be used if the CSS does not contain an `@charset` declaration.
+     *
      * @param string $sCharset
      *
      * @return void
@@ -75,6 +79,8 @@ public function setCharset($sCharset)
     }
 
     /**
+     * Returns the charset that is used if the CSS does not contain an `@charset` declaration.
+     *
      * @return string
      */
     public function getCharset()
diff --git a/src/Rule/Rule.php b/src/Rule/Rule.php
index 5f0b9f65..fc00c880 100644
--- a/src/Rule/Rule.php
+++ b/src/Rule/Rule.php
@@ -13,8 +13,9 @@
 use Sabberworm\CSS\Value\Value;
 
 /**
- * RuleSets contains Rule objects which always have a key and a value.
- * In CSS, Rules are expressed as follows: “key: value[0][0] value[0][1], value[1][0] value[1][1];”
+ * `Rule`s just have a string key (the rule) and a 'Value'.
+ *
+ * In CSS, `Rule`s are expressed as follows: “key: value[0][0] value[0][1], value[1][0] value[1][1];”
  */
 class Rule implements Renderable, Commentable
 {
diff --git a/src/RuleSet/AtRuleSet.php b/src/RuleSet/AtRuleSet.php
index 50958ef2..aab6d799 100644
--- a/src/RuleSet/AtRuleSet.php
+++ b/src/RuleSet/AtRuleSet.php
@@ -6,7 +6,10 @@
 use Sabberworm\CSS\Property\AtRule;
 
 /**
- * A RuleSet constructed by an unknown at-rule. `@font-face` rules are rendered into AtRuleSet objects.
+ * This class represents rule sets for generic at-rules which are not covered by specific classes, i.e., not
+ * `@import`, `@charset` or `@media`.
+ *
+ * A common example for this is `@font-face`.
  */
 class AtRuleSet extends RuleSet implements AtRule
 {
diff --git a/src/RuleSet/DeclarationBlock.php b/src/RuleSet/DeclarationBlock.php
index 3bebda67..de487bc1 100644
--- a/src/RuleSet/DeclarationBlock.php
+++ b/src/RuleSet/DeclarationBlock.php
@@ -19,7 +19,10 @@
 use Sabberworm\CSS\Value\Value;
 
 /**
- * Declaration blocks are the parts of a CSS file which denote the rules belonging to a selector.
+ * This class represents a `RuleSet` constrained by a `Selector`.
+ *
+ * It contains an array of selector objects (comma-separated in the CSS) as well as the rules to be applied to the
+ * matching elements.
  *
  * Declaration blocks usually appear directly inside a `Document` or another `CSSList` (mostly a `MediaQuery`).
  */
diff --git a/src/RuleSet/RuleSet.php b/src/RuleSet/RuleSet.php
index e7f4b82d..adb9be92 100644
--- a/src/RuleSet/RuleSet.php
+++ b/src/RuleSet/RuleSet.php
@@ -12,8 +12,13 @@
 use Sabberworm\CSS\Rule\Rule;
 
 /**
- * RuleSet is a generic superclass denoting rules. The typical example for rule sets are declaration block.
- * However, unknown At-Rules (like `@font-face`) are also rule sets.
+ * This class is a container for individual 'Rule's.
+ *
+ * The most common form of a rule set is one constrained by a selector, i.e., a `DeclarationBlock`.
+ * However, unknown `AtRule`s (like `@font-face`) are rule sets as well.
+ *
+ * If you want to manipulate a `RuleSet`, use the methods `addRule(Rule $rule)`, `getRules()` and `removeRule($rule)`
+ * (which accepts either a `Rule` or a rule name; optionally suffixed by a dash to remove all related rules).
  */
 abstract class RuleSet implements Renderable, Commentable
 {
diff --git a/src/Settings.php b/src/Settings.php
index 7b858096..79d99803 100644
--- a/src/Settings.php
+++ b/src/Settings.php
@@ -11,7 +11,8 @@ class Settings
 {
     /**
      * Multi-byte string support.
-     * If true (mbstring extension must be enabled), will use (slower) `mb_strlen`, `mb_convert_case`, `mb_substr`
+     *
+     * If `true` (`mbstring` extension must be enabled), will use (slower) `mb_strlen`, `mb_convert_case`, `mb_substr`
      * and `mb_strpos` functions. Otherwise, the normal (ASCII-Only) functions will be used.
      *
      * @var bool
@@ -19,15 +20,14 @@ class Settings
     public $bMultibyteSupport;
 
     /**
-     * The default charset for the CSS if no `@charset` rule is found. Defaults to utf-8.
+     * The default charset for the CSS if no `@charset` declaration is found. Defaults to utf-8.
      *
      * @var string
      */
     public $sDefaultCharset = 'utf-8';
 
     /**
-     * Lenient parsing. When used (which is true by default), the parser will not choke
-     * on unexpected tokens but simply ignore them.
+     * Whether the parser silently ignore invalid rules instead of choking on them.
      *
      * @var bool
      */
@@ -47,6 +47,11 @@ public static function create()
     }
 
     /**
+     * Enables/disables multi-byte string support.
+     *
+     * If `true` (`mbstring` extension must be enabled), will use (slower) `mb_strlen`, `mb_convert_case`, `mb_substr`
+     * and `mb_strpos` functions. Otherwise, the normal (ASCII-Only) functions will be used.
+     *
      * @param bool $bMultibyteSupport
      *
      * @return self fluent interface
@@ -58,6 +63,8 @@ public function withMultibyteSupport($bMultibyteSupport = true)
     }
 
     /**
+     * Sets the charset to be used if the CSS does not contain an `@charset` declaration.
+     *
      * @param string $sDefaultCharset
      *
      * @return self fluent interface
@@ -69,6 +76,8 @@ public function withDefaultCharset($sDefaultCharset)
     }
 
     /**
+     * Configures whether the parser should silently ignore invalid rules.
+     *
      * @param bool $bLenientParsing
      *
      * @return self fluent interface
@@ -80,6 +89,8 @@ public function withLenientParsing($bLenientParsing = true)
     }
 
     /**
+     * Configures the parser to choke on invalid rules.
+     *
      * @return self fluent interface
      */
     public function beStrict()
diff --git a/src/Value/CSSFunction.php b/src/Value/CSSFunction.php
index e6b8c118..95cae739 100644
--- a/src/Value/CSSFunction.php
+++ b/src/Value/CSSFunction.php
@@ -4,6 +4,10 @@
 
 use Sabberworm\CSS\OutputFormat;
 
+/**
+ * A `CSSFunction` represents a special kind of value that also contains a function name and where the values are the
+ * function’s arguments. It also handles equals-sign-separated argument lists like `filter: alpha(opacity=90);`.
+ */
 class CSSFunction extends ValueList
 {
     /**
diff --git a/src/Value/CSSString.php b/src/Value/CSSString.php
index 9fafedd7..da498d41 100644
--- a/src/Value/CSSString.php
+++ b/src/Value/CSSString.php
@@ -8,6 +8,11 @@
 use Sabberworm\CSS\Parsing\UnexpectedEOFException;
 use Sabberworm\CSS\Parsing\UnexpectedTokenException;
 
+/**
+ * This class is a wrapper for quoted strings to distinguish them from keywords.
+ *
+ * `CSSString`s always output with double quotes.
+ */
 class CSSString extends PrimitiveValue
 {
     /**
diff --git a/src/Value/Color.php b/src/Value/Color.php
index 8dc52960..dadbe3d8 100644
--- a/src/Value/Color.php
+++ b/src/Value/Color.php
@@ -7,6 +7,10 @@
 use Sabberworm\CSS\Parsing\UnexpectedEOFException;
 use Sabberworm\CSS\Parsing\UnexpectedTokenException;
 
+/**
+ * `Color's can be input in the form #rrggbb, #rgb or schema(val1, val2, …) but are always stored as an array of
+ * ('s' => val1, 'c' => val2, 'h' => val3, …) and output in the second form.
+ */
 class Color extends CSSFunction
 {
     /**
diff --git a/src/Value/RuleValueList.php b/src/Value/RuleValueList.php
index 5d533a7c..8fe88b61 100644
--- a/src/Value/RuleValueList.php
+++ b/src/Value/RuleValueList.php
@@ -2,6 +2,11 @@
 
 namespace Sabberworm\CSS\Value;
 
+/**
+ * This class is used to represent all multivalued rules like `font: bold 12px/3 Helvetica, Verdana, sans-serif;`
+ * (where the value would be a whitespace-separated list of the primitive value `bold`, a slash-separated list
+ * and a comma-separated list).
+ */
 class RuleValueList extends ValueList
 {
     /**
diff --git a/src/Value/Size.php b/src/Value/Size.php
index 6456ba79..9329f15b 100644
--- a/src/Value/Size.php
+++ b/src/Value/Size.php
@@ -7,6 +7,9 @@
 use Sabberworm\CSS\Parsing\UnexpectedEOFException;
 use Sabberworm\CSS\Parsing\UnexpectedTokenException;
 
+/**
+ * A `Size` consists of a numeric `size` value and a unit.
+ */
 class Size extends PrimitiveValue
 {
     /**
diff --git a/src/Value/URL.php b/src/Value/URL.php
index 1467d505..5d489eb3 100644
--- a/src/Value/URL.php
+++ b/src/Value/URL.php
@@ -8,6 +8,9 @@
 use Sabberworm\CSS\Parsing\UnexpectedEOFException;
 use Sabberworm\CSS\Parsing\UnexpectedTokenException;
 
+/**
+ * This class represents URLs in CSS. `URL`s always output in `URL("")` notation.
+ */
 class URL extends PrimitiveValue
 {
     /**
diff --git a/src/Value/Value.php b/src/Value/Value.php
index 66cb9fd4..fe773c74 100644
--- a/src/Value/Value.php
+++ b/src/Value/Value.php
@@ -8,6 +8,10 @@
 use Sabberworm\CSS\Parsing\UnexpectedTokenException;
 use Sabberworm\CSS\Renderable;
 
+/**
+ * Abstract base class for specific classes of CSS values: `Size`, `Color`, `CSSString` and `URL`, and another
+ * abstract subclass `ValueList`.
+ */
 abstract class Value implements Renderable
 {
     /**
diff --git a/src/Value/ValueList.php b/src/Value/ValueList.php
index af5348b9..a93acc7b 100644
--- a/src/Value/ValueList.php
+++ b/src/Value/ValueList.php
@@ -4,6 +4,12 @@
 
 use Sabberworm\CSS\OutputFormat;
 
+/**
+ * A `ValueList` represents a lists of `Value`s, separated by some separation character
+ * (mostly `,`, whitespace, or `/`).
+ *
+ * There are two types of `ValueList`s: `RuleValueList` and `CSSFunction`
+ */
 abstract class ValueList extends Value
 {
     /**