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

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

Author: oliverklee

CHANGELOG.md

@@ -21,6 +21,7 @@ Please also have a look at our
 
 ### Changed
 
+- Make all non-private properties `@internal` (#886)
 - Use more native type declarations and strict mode
   (#641, #772, #774, #778, #804, #841, #873, #875)
 - Add visibility to all class/interface constants (#469)

src/CSSList/CSSList.php

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

src/Comment/Comment.php

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

src/OutputFormat.php

@@ -10,13 +10,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;
 
@@ -26,6 +30,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;
 
@@ -34,60 +40,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 = ' ';
 
@@ -98,13 +128,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 = [];
 
@@ -115,56 +149,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

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

src/Property/Charset.php

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

src/Property/Import.php

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

src/Rule/Rule.php

@@ -48,11 +48,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 $comments;
 

src/RuleSet/RuleSet.php

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

src/Settings.php

@@ -18,20 +18,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

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

src/Value/Value.php

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

src/Value/ValueList.php

@@ -16,11 +16,15 @@ abstract class ValueList extends Value
 {
     /**
      * @var array<array-key, Value|string>
+     *
+     * @internal since 8.8.0
      */
     protected $aComponents;
 
     /**
      * @var string
+     *
+     * @internal since 8.8.0
      */
     protected $sSeparator;