Merge pull request #206 from oliverklee/cleanup/type-annotations

Add some PHPDoc type annotations

Author: sabberworm

lib/Sabberworm/CSS/CSSList/AtRuleBlockList.php

@@ -8,20 +8,37 @@
  * A BlockList constructed by an unknown @-rule. @media rules are rendered into AtRuleBlockList objects.
  */
 class AtRuleBlockList extends CSSBlockList implements AtRule {
-
+	/**
+	 * @var string
+	 */
 	private $sType;
+
+	/**
+	 * @var string
+	 */
 	private $sArgs;
 
+	/**
+	 * @param string $sType
+	 * @param string $sArgs
+	 * @param int $iLineNo
+	 */
 	public function __construct($sType, $sArgs = '', $iLineNo = 0) {
 		parent::__construct($iLineNo);
 		$this->sType = $sType;
 		$this->sArgs = $sArgs;
 	}
 
+	/**
+	 * @return string
+	 */
 	public function atRuleName() {
 		return $this->sType;
 	}
 
+	/**
+	 * @return string
+	 */
 	public function atRuleArgs() {
 		return $this->sArgs;
 	}
@@ -30,6 +47,9 @@ public function __toString() {
 		return $this->render(new \Sabberworm\CSS\OutputFormat());
 	}
 
+	/**
+	 * @return string
+	 */
 	public function render(\Sabberworm\CSS\OutputFormat $oOutputFormat) {
 		$sArgs = $this->sArgs;
 		if($sArgs) {

lib/Sabberworm/CSS/CSSList/CSSList.php

@@ -25,11 +25,24 @@
  * Also, it may contain Import and Charset objects stemming from @-rules.
  */
 abstract class CSSList implements Renderable, Commentable {
-
+	/**
+	 * @var array
+	 */
 	protected $aComments;
+
+	/**
+	 * @var array<int, RuleSet|Import|Charset|CSSList>
+	 */
 	protected $aContents;
+
+	/**
+	 * @var int
+	 */
 	protected $iLineNo;
 
+	/**
+	 * @param int $iLineNo
+	 */
 	public function __construct($iLineNo = 0) {
 		$this->aComments = array();
 		$this->aContents = array();
@@ -195,7 +208,7 @@ public function getLineNo() {
 	/**
 	 * Prepend item to list of contents.
 	 *
-	 * @param object $oItem Item.
+	 * @param RuleSet|Import|Charset|CSSList $oItem Item.
 	 */
 	public function prepend($oItem) {
 		array_unshift($this->aContents, $oItem);
@@ -204,7 +217,7 @@ public function prepend($oItem) {
 	/**
 	 * Append item to list of contents.
 	 *
-	 * @param object $oItem Item.
+	 * @param RuleSet|Import|Charset|CSSList $oItem Item.
 	 */
 	public function append($oItem) {
 		$this->aContents[] = $oItem;
@@ -237,6 +250,7 @@ public function remove($oItemToRemove) {
 
 	/**
 	 * Replaces an item from the CSS list.
+	 *
 	 * @param RuleSet|Import|Charset|CSSList $oItemToRemove May be a RuleSet (most likely a DeclarationBlock), a Import, a Charset or another CSSList (most likely a MediaQuery)
 	 */
 	public function replace($oOldItem, $mNewItem) {
@@ -254,7 +268,7 @@ public function replace($oOldItem, $mNewItem) {
 
 	/**
 	 * Set the contents.
-	 * @param array $aContents Objects to set as content.
+	 * @param array<int, RuleSet|Import|Charset|CSSList> $aContents Objects to set as content.
 	 */
 	public function setContents(array $aContents) {
 		$this->aContents = array();
@@ -300,6 +314,9 @@ public function __toString() {
 		return $this->render(new \Sabberworm\CSS\OutputFormat());
 	}
 
+	/**
+	 * @return string
+	 */
 	public function render(\Sabberworm\CSS\OutputFormat $oOutputFormat) {
 		$sResult = '';
 		$bIsFirst = true;
@@ -330,12 +347,15 @@ public function render(\Sabberworm\CSS\OutputFormat $oOutputFormat) {
 
 		return $sResult;
 	}
-	
+
 	/**
 	* Return true if the list can not be further outdented. Only important when rendering.
 	*/
 	public abstract function isRootList();
 
+	/**
+	 * @return array<int, RuleSet|Import|Charset|CSSList>
+	 */
 	public function getContents() {
 		return $this->aContents;
 	}

lib/Sabberworm/CSS/CSSList/Document.php

@@ -16,6 +16,13 @@ public function __construct($iLineNo = 0) {
 		parent::__construct($iLineNo);
 	}
 
+	/**
+	 * @param ParserState $oParserState
+	 *
+	 * @return Document
+	 *
+	 * @throws \Sabberworm\CSS\Parsing\SourceException
+	 */
 	public static function parse(ParserState $oParserState) {
 		$oDocument = new Document($oParserState->currentLine());
 		CSSList::parseList($oParserState, $oDocument);
@@ -95,7 +102,14 @@ public function createShorthands() {
 		}
 	}
 
-	// Override render() to make format argument optional
+
+	/**
+	 * Override render() to make format argument optional
+	 *
+	 * @param \Sabberworm\CSS\OutputFormat|null $oOutputFormat
+	 *
+	 * @return string
+	 */
 	public function render(\Sabberworm\CSS\OutputFormat $oOutputFormat = null) {
 		if($oOutputFormat === null) {
 			$oOutputFormat = new \Sabberworm\CSS\OutputFormat();

lib/Sabberworm/CSS/CSSList/KeyFrame.php

@@ -5,8 +5,14 @@
 use Sabberworm\CSS\Property\AtRule;
 
 class KeyFrame extends CSSList implements AtRule {
-
+	/**
+	 * @var string|null
+	 */
 	private $vendorKeyFrame;
+
+	/**
+	 * @var string|null
+	 */
 	private $animationName;
 
 	public function __construct($iLineNo = 0) {
@@ -35,6 +41,11 @@ public function __toString() {
 		return $this->render(new \Sabberworm\CSS\OutputFormat());
 	}
 
+	/**
+	 * @param \Sabberworm\CSS\OutputFormat $oOutputFormat
+	 *
+	 * @return string
+	 */
 	public function render(\Sabberworm\CSS\OutputFormat $oOutputFormat) {
 		$sResult = "@{$this->vendorKeyFrame} {$this->animationName}{$oOutputFormat->spaceBeforeOpeningBrace()}{";
 		$sResult .= parent::render($oOutputFormat);
@@ -46,10 +57,16 @@ public function isRootList() {
 		return false;
 	}
 
+	/**
+	 * @return string|null
+	 */
 	public function atRuleName() {
 		return $this->vendorKeyFrame;
 	}
 
+	/**
+	 * @return string|null
+	 */
 	public function atRuleArgs() {
 		return $this->animationName;
 	}

lib/Sabberworm/CSS/Parser.php

@@ -9,6 +9,9 @@
  * Parser class parses CSS from text into a data structure.
  */
 class Parser {
+	/**
+	 * @var ParserState
+	 */
 	private $oParserState;
 
 	/**
@@ -34,8 +37,12 @@ public function getCharset() {
 		$this->oParserState->getCharset();
 	}
 
+	/**
+	 * @return Document
+	 *
+	 * @throws Parsing\SourceException
+	 */
 	public function parse() {
 		return Document::parse($this->oParserState);
 	}
-
 }

lib/Sabberworm/CSS/Property/AtRule.php

@@ -10,7 +10,14 @@ interface AtRule extends Renderable, Commentable {
 	const BLOCK_RULES = 'media/document/supports/region-style/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';
-	
+
+	/**
+	 * @return string|null
+	 */
 	public function atRuleName();
+
+	/**
+	 * @return string|null
+	 */
 	public function atRuleArgs();
 }

lib/Sabberworm/CSS/Property/CSSNamespace.php

@@ -10,7 +10,7 @@ class CSSNamespace implements AtRule {
 	private $sPrefix;
 	private $iLineNo;
 	protected $aComments;
-	
+
 	public function __construct($mUrl, $sPrefix = null, $iLineNo = 0) {
 		$this->mUrl = $mUrl;
 		$this->sPrefix = $sPrefix;
@@ -29,10 +29,15 @@ public function __toString() {
 		return $this->render(new \Sabberworm\CSS\OutputFormat());
 	}
 
+	/**
+	 * @param \Sabberworm\CSS\OutputFormat $oOutputFormat
+	 *
+	 * @return string
+	 */
 	public function render(\Sabberworm\CSS\OutputFormat $oOutputFormat) {
 		return '@namespace '.($this->sPrefix === null ? '' : $this->sPrefix.' ').$this->mUrl->render($oOutputFormat).';';
 	}
-	
+
 	public function getUrl() {
 		return $this->mUrl;
 	}
@@ -49,10 +54,16 @@ public function setPrefix($sPrefix) {
 		$this->sPrefix = $sPrefix;
 	}
 
+	/**
+	 * @return string
+	 */
 	public function atRuleName() {
 		return 'namespace';
 	}
 
+	/**
+	 * @return array<int, string>
+	 */
 	public function atRuleArgs() {
 		$aResult = array($this->mUrl);
 		if($this->sPrefix) {

lib/Sabberworm/CSS/Property/Charset.php

@@ -10,11 +10,25 @@
  * • Must not appear more than once.
  */
 class Charset implements AtRule {
-
+	/**
+	 * @var string
+	 */
 	private $sCharset;
+
+	/**
+	 * @var int
+	 */
 	protected $iLineNo;
+
+	/**
+	 * @var array
+	 */
 	protected $aComment;
 
+	/**
+	 * @param string $sCharset
+	 * @param int $iLineNo
+	 */
 	public function __construct($sCharset, $iLineNo = 0) {
 		$this->sCharset = $sCharset;
 		$this->iLineNo = $iLineNo;
@@ -40,14 +54,25 @@ public function __toString() {
 		return $this->render(new \Sabberworm\CSS\OutputFormat());
 	}
 
+	/**
+	 * @param \Sabberworm\CSS\OutputFormat $oOutputFormat
+	 *
+	 * @return string
+	 */
 	public function render(\Sabberworm\CSS\OutputFormat $oOutputFormat) {
 		return "@charset {$this->sCharset->render($oOutputFormat)};";
 	}
 
+	/**
+	 * @return string
+	 */
 	public function atRuleName() {
 		return 'charset';
 	}
 
+	/**
+	 * @return string
+	 */
 	public function atRuleArgs() {
 		return $this->sCharset;
 	}
@@ -63,4 +88,4 @@ public function getComments() {
 	public function setComments(array $aComments) {
 		$this->aComments = $aComments;
 	}
-}
+}