[TASK] Make all non-private properties @internal (#889)

This communicates clearly that the properties may be
removed, renamed or made `private` at any point, and that
they should not be accessed directly, but using the accessors
instead.

Also add a type annotation that was missing.

Fixes #881

This is the V8.x backport of #886.

Author: oliverklee

CHANGELOG.md

@@ -11,6 +11,8 @@ This project adheres to [Semantic Versioning](https://semver.org/).
 
 ### Changed
 
+- Make all non-private properties `@internal` (#886)
+
 ### Deprecated
 
 - `OutputFormat` properties for space around list separators as an array (#880)

src/CSSList/CSSList.php

@@ -33,16 +33,22 @@ abstract class CSSList implements Renderable, Commentable
 {
     /**
      * @var array<array-key, Comment>
+     *
+     * @internal since 8.8.0
      */
     protected $aComments;
 
     /**
      * @var array<int, RuleSet|CSSList|Import|Charset>
+     *
+     * @internal since 8.8.0
      */
     protected $aContents;
 
     /**
      * @var int
+     *
+     * @internal since 8.8.0
      */
     protected $iLineNo;
 

src/Comment/Comment.php

@@ -9,11 +9,15 @@ class Comment implements Renderable
 {
     /**
      * @var int
+     *
+     * @internal since 8.8.0
      */
     protected $iLineNo;
 
     /**
      * @var string
+     *
+     * @internal since 8.8.0
      */
     protected $sComment;
 

src/OutputFormat.php

@@ -14,13 +14,17 @@ class OutputFormat
      * Value format: `"` means double-quote, `'` means single-quote
      *
      * @var string
+     *
+     * @internal since 8.8.0, will be made private in 9.0.0
      */
     public $sStringQuotingType = '"';
 
     /**
      * Output RGB colors in hash notation if possible
      *
      * @var string
+     *
+     * @internal since 8.8.0, will be made private in 9.0.0
      */
     public $bRGBHashNotation = true;
 
@@ -30,6 +34,8 @@ class OutputFormat
      * Semicolon after the last rule of a declaration block can be omitted. To do that, set this false.
      *
      * @var bool
+     *
+     * @internal since 8.8.0, will be made private in 9.0.0
      */
     public $bSemicolonAfterLastRule = true;
 
@@ -38,60 +44,84 @@ class OutputFormat
      * Note that these strings are not sanity-checked: the value should only consist of whitespace
      * Any newline character will be indented according to the current level.
      * The triples (After, Before, Between) can be set using a wildcard (e.g. `$oFormat->set('Space*Rules', "\n");`)
+     *
+     * @var string
+     *
+     * @internal since 8.8.0, will be made private in 9.0.0
      */
     public $sSpaceAfterRuleName = ' ';
 
     /**
      * @var string
+     *
+     * @internal since 8.8.0, will be made private in 9.0.0
      */
     public $sSpaceBeforeRules = '';
 
     /**
      * @var string
+     *
+     * @internal since 8.8.0, will be made private in 9.0.0
      */
     public $sSpaceAfterRules = '';
 
     /**
      * @var string
+     *
+     * @internal since 8.8.0, will be made private in 9.0.0
      */
     public $sSpaceBetweenRules = '';
 
     /**
      * @var string
+     *
+     * @internal since 8.8.0, will be made private in 9.0.0
      */
     public $sSpaceBeforeBlocks = '';
 
     /**
      * @var string
+     *
+     * @internal since 8.8.0, will be made private in 9.0.0
      */
     public $sSpaceAfterBlocks = '';
 
     /**
      * @var string
+     *
+     * @internal since 8.8.0, will be made private in 9.0.0
      */
     public $sSpaceBetweenBlocks = "\n";
 
     /**
      * Content injected in and around at-rule blocks.
      *
      * @var string
+     *
+     * @internal since 8.8.0, will be made private in 9.0.0
      */
     public $sBeforeAtRuleBlock = '';
 
     /**
      * @var string
+     *
+     * @internal since 8.8.0, will be made private in 9.0.0
      */
     public $sAfterAtRuleBlock = '';
 
     /**
      * This is what’s printed before and after the comma if a declaration block contains multiple selectors.
      *
      * @var string
+     *
+     * @internal since 8.8.0, will be made private in 9.0.0
      */
     public $sSpaceBeforeSelectorSeparator = '';
 
     /**
      * @var string
+     *
+     * @internal since 8.8.0, will be made private in 9.0.0
      */
     public $sSpaceAfterSelectorSeparator = ' ';
 
@@ -102,13 +132,17 @@ class OutputFormat
      * To set the spacing for specific separators, use {@see $aSpaceBeforeListArgumentSeparators} instead.
      *
      * @var string|array<non-empty-string, string>
+     *
+     * @internal since 8.8.0, will be made private in 9.0.0
      */
     public $sSpaceBeforeListArgumentSeparator = '';
 
     /**
      * Keys are separators (e.g. `,`).  Values are the space sequence to insert, or an empty string.
      *
      * @var array<non-empty-string, string>
+     *
+     * @internal since 8.8.0, will be made private in 9.0.0
      */
     public $aSpaceBeforeListArgumentSeparators = [];
 
@@ -119,56 +153,74 @@ class OutputFormat
      * To set the spacing for specific separators, use {@see $aSpaceAfterListArgumentSeparators} instead.
      *
      * @var string|array<non-empty-string, string>
+     *
+     * @internal since 8.8.0, will be made private in 9.0.0
      */
     public $sSpaceAfterListArgumentSeparator = '';
 
     /**
      * Keys are separators (e.g. `,`).  Values are the space sequence to insert, or an empty string.
      *
      * @var array<non-empty-string, string>
+     *
+     * @internal since 8.8.0, will be made private in 9.0.0
      */
     public $aSpaceAfterListArgumentSeparators = [];
 
     /**
      * @var string
+     *
+     * @internal since 8.8.0, will be made private in 9.0.0
      */
     public $sSpaceBeforeOpeningBrace = ' ';
 
     /**
      * Content injected in and around declaration blocks.
      *
      * @var string
+     *
+     * @internal since 8.8.0, will be made private in 9.0.0
      */
     public $sBeforeDeclarationBlock = '';
 
     /**
      * @var string
+     *
+     * @internal since 8.8.0, will be made private in 9.0.0
      */
     public $sAfterDeclarationBlockSelectors = '';
 
     /**
      * @var string
+     *
+     * @internal since 8.8.0, will be made private in 9.0.0
      */
     public $sAfterDeclarationBlock = '';
 
     /**
      * Indentation character(s) per level. Only applicable if newlines are used in any of the spacing settings.
      *
      * @var string
+     *
+     * @internal since 8.8.0, will be made private in 9.0.0
      */
     public $sIndentation = "\t";
 
     /**
      * Output exceptions.
      *
      * @var bool
+     *
+     * @internal since 8.8.0, will be made private in 9.0.0
      */
     public $bIgnoreExceptions = false;
 
     /**
      * Render comments for lists and RuleSets
      *
      * @var bool
+     *
+     * @internal since 8.8.0, will be made private in 9.0.0
      */
     public $bRenderComments = false;
 

src/Property/CSSNamespace.php

@@ -27,6 +27,8 @@ class CSSNamespace implements AtRule
 
     /**
      * @var array<array-key, Comment>
+     *
+     * @internal since 8.8.0
      */
     protected $aComments;
 

src/Property/Charset.php

@@ -23,11 +23,15 @@ class Charset implements AtRule
 
     /**
      * @var int
+     *
+     * @internal since 8.8.0
      */
     protected $iLineNo;
 
     /**
      * @var array<array-key, Comment>
+     *
+     * @internal since 8.8.0
      */
     protected $aComments;
 

src/Property/Import.php

@@ -23,11 +23,15 @@ class Import implements AtRule
 
     /**
      * @var int
+     *
+     * @internal since 8.8.0
      */
     protected $iLineNo;
 
     /**
      * @var array<array-key, Comment>
+     *
+     * @internal since 8.8.0
      */
     protected $aComments;
 

src/Rule/Rule.php

@@ -46,11 +46,15 @@ class Rule implements Renderable, Commentable
 
     /**
      * @var int
+     *
+     * @internal since 8.8.0
      */
     protected $iColNo;
 
     /**
      * @var array<array-key, Comment>
+     *
+     * @internal since 8.8.0
      */
     protected $aComments;
 

src/RuleSet/RuleSet.php

@@ -29,11 +29,15 @@ abstract class RuleSet implements Renderable, Commentable
 
     /**
      * @var int
+     *
+     * @internal since 8.8.0
      */
     protected $iLineNo;
 
     /**
      * @var array<array-key, Comment>
+     *
+     * @internal since 8.8.0
      */
     protected $aComments;
 

src/Settings.php

@@ -16,20 +16,26 @@ class Settings
      * and `mb_strpos` functions. Otherwise, the normal (ASCII-Only) functions will be used.
      *
      * @var bool
+     *
+     * @internal since 8.8.0, will be made private in 9.0.0
      */
     public $bMultibyteSupport;
 
     /**
      * The default charset for the CSS if no `@charset` declaration is found. Defaults to utf-8.
      *
      * @var string
+     *
+     * @internal since 8.8.0, will be made private in 9.0.0
      */
     public $sDefaultCharset = 'utf-8';
 
     /**
      * Whether the parser silently ignore invalid rules instead of choking on them.
      *
      * @var bool
+     *
+     * @internal since 8.8.0, will be made private in 9.0.0
      */
     public $bLenientParsing = true;
 

src/Value/CSSFunction.php

@@ -13,6 +13,8 @@ class CSSFunction extends ValueList
 {
     /**
      * @var string
+     *
+     * @internal since 8.8.0
      */
     protected $sName;
 

src/Value/Value.php

@@ -16,6 +16,8 @@ abstract class Value implements Renderable
 {
     /**
      * @var int
+     *
+     * @internal since 8.8.0
      */
     protected $iLineNo;
 

src/Value/ValueList.php

@@ -14,11 +14,15 @@ abstract class ValueList extends Value
 {
     /**
      * @var array<int, RuleValueList|CSSFunction|CSSString|LineName|Size|URL|string>
+     *
+     * @internal since 8.8.0
      */
     protected $aComponents;
 
     /**
      * @var string
+     *
+     * @internal since 8.8.0
      */
     protected $sSeparator;