From 192d0043f98a161278088e5167e3b0814c2a2d3b Mon Sep 17 00:00:00 2001 From: Oliver Klee Date: Fri, 18 Jun 2021 20:40:44 +0200 Subject: [PATCH 1/2] Streamline the existing PHPDoc comments Make them more useful for static code analysis, for human readers and for rendering. --- src/CSSList/CSSList.php | 4 +-- src/Comment/Comment.php | 2 +- src/OutputFormat.php | 47 ++++++++++++++++++++++++------- src/OutputFormatter.php | 4 +-- src/Parser.php | 3 +- src/Parsing/ParserState.php | 2 +- src/Property/AtRule.php | 2 +- src/Property/Import.php | 2 +- src/Property/KeyframeSelector.php | 7 +++-- src/Property/Selector.php | 16 ++++++++++- src/Rule/Rule.php | 4 +-- src/RuleSet/AtRuleSet.php | 2 +- src/RuleSet/DeclarationBlock.php | 34 +++++++++++----------- src/RuleSet/RuleSet.php | 8 +++--- src/Settings.php | 10 +++++-- tests/ParserTest.php | 2 +- 16 files changed, 100 insertions(+), 49 deletions(-) diff --git a/src/CSSList/CSSList.php b/src/CSSList/CSSList.php index 0ec08886..3545c2bb 100644 --- a/src/CSSList/CSSList.php +++ b/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) */ diff --git a/src/Comment/Comment.php b/src/Comment/Comment.php index 555130e2..6b19fb64 100644 --- a/src/Comment/Comment.php +++ b/src/Comment/Comment.php @@ -34,7 +34,7 @@ public function getLineNo() } /** - * @return string + * @param string $sComment */ public function setComment($sComment) { diff --git a/src/OutputFormat.php b/src/OutputFormat.php index a2124ead..096d763f 100644 --- a/src/OutputFormat.php +++ b/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,24 +53,40 @@ 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 = ''; @@ -70,13 +94,16 @@ class OutputFormat 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; diff --git a/src/OutputFormatter.php b/src/OutputFormatter.php index 50a2fe22..6abb9c3e 100644 --- a/src/OutputFormatter.php +++ b/src/OutputFormatter.php @@ -99,7 +99,7 @@ public function safely($cCode) return $cCode(); } catch (OutputException $e) { return null; - } //Do nothing + } // Do nothing } else { // Run the code as-is return $cCode(); @@ -107,7 +107,7 @@ public function safely($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) { diff --git a/src/Parser.php b/src/Parser.php index 6f017c89..7435db35 100644 --- a/src/Parser.php +++ b/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 diff --git a/src/Parsing/ParserState.php b/src/Parsing/ParserState.php index 67ef5efb..306a317e 100644 --- a/src/Parsing/ParserState.php +++ b/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); diff --git a/src/Property/AtRule.php b/src/Property/AtRule.php index 0a87684f..4cc95352 100644 --- a/src/Property/AtRule.php +++ b/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'; /** diff --git a/src/Property/Import.php b/src/Property/Import.php index 72d1396b..beca0ff2 100644 --- a/src/Property/Import.php +++ b/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 { diff --git a/src/Property/KeyframeSelector.php b/src/Property/KeyframeSelector.php index 8d6b6e78..517a6b51 100644 --- a/src/Property/KeyframeSelector.php +++ b/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 = '/ ^( (?: diff --git a/src/Property/Selector.php b/src/Property/Selector.php index d2459fb1..c0aad2a5 100644 --- a/src/Property/Selector.php +++ b/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 = '/ ^( (?: diff --git a/src/Rule/Rule.php b/src/Rule/Rule.php index 29fbc2e8..29d8cb6e 100644 --- a/src/Rule/Rule.php +++ b/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() { diff --git a/src/RuleSet/AtRuleSet.php b/src/RuleSet/AtRuleSet.php index 80370053..2c29af7c 100644 --- a/src/RuleSet/AtRuleSet.php +++ b/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 @-rule. `@font-face` rules are rendered into AtRuleSet objects. */ class AtRuleSet extends RuleSet implements AtRule { diff --git a/src/RuleSet/DeclarationBlock.php b/src/RuleSet/DeclarationBlock.php index 1c3b661d..628b7ee7 100644 --- a/src/RuleSet/DeclarationBlock.php +++ b/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,7 +120,7 @@ public function removeSelector($mSelector) } /** - * @deprecated use getSelectors() + * @deprecated use `getSelectors()` */ public function getSelector() { @@ -126,7 +128,7 @@ public function getSelector() } /** - * @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. font: 300 italic 11px/14px verdana, helvetica, sans-serif;) + * (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. background: url("chess.png") gray 50% repeat fixed;) + /** + * 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. font-weight) and - * tries to convert them into a shorthand CSS font 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 = [ diff --git a/src/RuleSet/RuleSet.php b/src/RuleSet/RuleSet.php index 7fcb64c2..614ed6f7 100644 --- a/src/RuleSet/RuleSet.php +++ b/src/RuleSet/RuleSet.php @@ -11,7 +11,7 @@ /** * 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. + * However, unknown At-Rules (like `@font-face`) are also rule sets. */ abstract class RuleSet implements Renderable, Commentable { @@ -162,8 +162,8 @@ public function setRules(array $aRules) * Returns all rules matching the given pattern and returns them in an associative array with the rule’s name * as keys. This method exists mainly for backwards-compatibility and is really only partially useful. * - * Note: This method loses some information: Calling this (with an argument of 'background-') on a declaration block - * like { background-color: green; background-color; rgba(0, 127, 0, 0.7); } will only yield an associative array + * Note: This method loses some information: Calling this (with an argument of `background-`) on a declaration block + * like `{ background-color: green; background-color; rgba(0, 127, 0, 0.7); }` will only yield an associative array * containing the rgba-valued rule while `getRules()` would yield an indexed array containing both. * * @param string $mRule @@ -183,7 +183,7 @@ public function getRulesAssoc($mRule = null) } /** - * Remove a rule from this RuleSet. This accepts all the possible values that `getRules()` accepts. + * Removes a rule from this RuleSet. This accepts all the possible values that `getRules()` accepts. * * If given a Rule, it will only remove this particular rule (by identity). * If given a name, it will remove all rules by that name. diff --git a/src/Settings.php b/src/Settings.php index 789ba184..5cf38832 100644 --- a/src/Settings.php +++ b/src/Settings.php @@ -11,19 +11,25 @@ class Settings { /** * 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. + * 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 */ public $bMultibyteSupport; /** * The default charset for the CSS if no `@charset` rule 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. + * + * @var bool */ public $bLenientParsing = true; diff --git a/tests/ParserTest.php b/tests/ParserTest.php index 2ffb0097..fccb742d 100644 --- a/tests/ParserTest.php +++ b/tests/ParserTest.php @@ -802,7 +802,7 @@ public function testMissingPropertyValueLenient() * Parse structure for file. * * @param string $sFileName Filename. - * @param null|obJeCt $oSettings Settings. + * @param Settings|null $oSettings Settings. * * @return Document Parsed document. */ From 36eb51053b46ec8dfa078862620fbb3ce6311b2b Mon Sep 17 00:00:00 2001 From: Oliver Klee Date: Sat, 19 Jun 2021 11:20:17 +0200 Subject: [PATCH 2/2] Change the wording of at-rules in PHPDoc At-rules should be written as "`at-rules`", not as "`@-rules`", as the `@` character is used to mark PHPDoc annotations. (In addition, the naming then is consistent with the terminology used at https://developer.mozilla.org/en-US/docs/Web/CSS/Syntax.) --- src/CSSList/AtRuleBlockList.php | 2 +- src/CSSList/CSSList.php | 2 +- src/CSSList/Document.php | 2 +- src/OutputFormat.php | 2 +- src/RuleSet/AtRuleSet.php | 2 +- 5 files changed, 5 insertions(+), 5 deletions(-) diff --git a/src/CSSList/AtRuleBlockList.php b/src/CSSList/AtRuleBlockList.php index ecf3762d..ce3a74e4 100644 --- a/src/CSSList/AtRuleBlockList.php +++ b/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 { diff --git a/src/CSSList/CSSList.php b/src/CSSList/CSSList.php index 3545c2bb..752339cf 100644 --- a/src/CSSList/CSSList.php +++ b/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 { diff --git a/src/CSSList/Document.php b/src/CSSList/Document.php index 53490133..77a15a2b 100644 --- a/src/CSSList/Document.php +++ b/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 { diff --git a/src/OutputFormat.php b/src/OutputFormat.php index 096d763f..d220a585 100644 --- a/src/OutputFormat.php +++ b/src/OutputFormat.php @@ -54,7 +54,7 @@ class OutputFormat public $sSpaceBetweenBlocks = "\n"; /** - * Content injected in and around @-rule blocks. + * Content injected in and around at-rule blocks. * * @var string */ diff --git a/src/RuleSet/AtRuleSet.php b/src/RuleSet/AtRuleSet.php index 2c29af7c..94179208 100644 --- a/src/RuleSet/AtRuleSet.php +++ b/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 {