Better PHPDocs for return

Author: Alkarex

src/XlsxFastEditor.php

@@ -185,6 +185,7 @@ private function getDomFromPath(string $path): \DOMDocument
 	 * Excel can either use a base date from year 1900 (Microsoft Windows) or from year 1904 (old Apple MacOS).
 	 * https://support.microsoft.com/en-us/office/date-systems-in-excel-e7fe7167-48a9-4b96-bb53-5612a800b487
 	 * @phpstan-return 1900|1904
+	 * @return int 1900 or 1904
 	 * @throws XlsxFastEditorFileFormatException
 	 * @throws XlsxFastEditorXmlException
 	 */
@@ -409,7 +410,7 @@ public function getRow(int $sheetNumber, int $rowNumber, int $accessMode = XlsxF
 	/**
 	 * Get the first existing row of the worksheet.
 	 * @param int $sheetNumber Worksheet number (base 1)
-	 * @return XlsxFastEditorRow|null The first row of the worksheet if there is any row, null otherwise.
+	 * @return XlsxFastEditorRow|null The first row of the worksheet if there is any row, `null` otherwise.
 	 * @throws XlsxFastEditorFileFormatException
 	 * @throws XlsxFastEditorXmlException
 	 */
@@ -430,7 +431,7 @@ public function getFirstRow(int $sheetNumber): ?XlsxFastEditorRow
 	/**
 	 * Get the last existing row of the worksheet.
 	 * @param int $sheetNumber Worksheet number (base 1)
-	 * @return XlsxFastEditorRow|null The last row of the worksheet if there is any row, null otherwise.
+	 * @return XlsxFastEditorRow|null The last row of the worksheet if there is any row, `null` otherwise.
 	 * @throws XlsxFastEditorFileFormatException
 	 * @throws XlsxFastEditorXmlException
 	 */
@@ -451,6 +452,7 @@ public function getLastRow(int $sheetNumber): ?XlsxFastEditorRow
 	/**
 	 * Delete the specified row of the specified worksheet.
 	 * @param int $sheetNumber Worksheet number (base 1)
+	 * @return bool True if the deletion succeeds, false otherwise.
 	 * @throws XlsxFastEditorFileFormatException
 	 * @throws XlsxFastEditorXmlException
 	 */
@@ -671,6 +673,7 @@ public function getCellAutocreate(int $sheetNumber, string $cellName): XlsxFastE
 	 *
 	 * @param int $sheetNumber Worksheet number (base 1)
 	 * @param string $cellName Cell name such as `B4`
+	 * @return string|null an integer if the cell exists and contains a formula, `null` otherwise.
 	 * @throws \InvalidArgumentException if `$cellName` has an invalid format
 	 * @throws XlsxFastEditorFileFormatException
 	 * @throws XlsxFastEditorXmlException
@@ -686,6 +689,7 @@ public function readFormula(int $sheetNumber, string $cellName): ?string
 	 *
 	 * @param int $sheetNumber Worksheet number (base 1)
 	 * @param string $cellName Cell name such as `B4`
+	 * @return float|null a float if the cell exists and contains a number, `null` otherwise.
 	 * @throws \InvalidArgumentException if `$cellName` has an invalid format
 	 * @throws XlsxFastEditorFileFormatException
 	 * @throws XlsxFastEditorXmlException
@@ -701,6 +705,7 @@ public function readFloat(int $sheetNumber, string $cellName): ?float
 	 *
 	 * @param int $sheetNumber Worksheet number (base 1)
 	 * @param string $cellName Cell name such as `B4`
+	 * @return \DateTimeImmutable|null a date if the cell exists and contains a number, `null` otherwise.
 	 * @throws \InvalidArgumentException if `$cellName` has an invalid format
 	 * @throws XlsxFastEditorFileFormatException
 	 * @throws XlsxFastEditorXmlException
@@ -716,6 +721,7 @@ public function readDateTime(int $sheetNumber, string $cellName): ?\DateTimeImmu
 	 *
 	 * @param int $sheetNumber Worksheet number (base 1)
 	 * @param string $cellName Cell name such as `B4`
+	 * @return int|null an integer if the cell exists and contains a number, `null` otherwise.
 	 * @throws \InvalidArgumentException if `$cellName` has an invalid format
 	 * @throws XlsxFastEditorFileFormatException
 	 * @throws XlsxFastEditorXmlException
@@ -755,6 +761,7 @@ public function _getSharedString(int $stringNumber): ?string
 	 *
 	 * @param int $sheetNumber Worksheet number (base 1)
 	 * @param string $cellName Cell name such as `B4`
+	 * @return string|null a string if the cell exists and contains a value, `null` otherwise.
 	 * @throws \InvalidArgumentException if `$cellName` has an invalid format
 	 * @throws XlsxFastEditorFileFormatException
 	 * @throws XlsxFastEditorXmlException
@@ -797,6 +804,7 @@ public function _getHyperlink(int $sheetNumber, string $rId): ?string
 	 *
 	 * @param int $sheetNumber Worksheet number (base 1)
 	 * @param string $cellName Cell name such as `B4`
+	 * @return string|null a string if the cell exists and contains a hyperlink, `null` otherwise.
 	 * @throws \InvalidArgumentException if `$cellName` has an invalid format
 	 * @throws XlsxFastEditorFileFormatException
 	 * @throws XlsxFastEditorXmlException

src/XlsxFastEditorCell.php

@@ -61,7 +61,7 @@ public function column(): string
 	}
 
 	/**
-	 * Access the previous existing cell, if any, null otherwise.
+	 * Access the previous existing cell, if any, `null` otherwise.
 	 */
 	public function getPreviousCell(): ?XlsxFastEditorCell
 	{
@@ -76,7 +76,7 @@ public function getPreviousCell(): ?XlsxFastEditorCell
 	}
 
 	/**
-	 * Access the next existing cell, if any, null otherwise.
+	 * Access the next existing cell, if any, `null` otherwise.
 	 */
 	public function getNextCell(): ?XlsxFastEditorCell
 	{
@@ -105,6 +105,7 @@ public function getRow(): XlsxFastEditorRow
 
 	/**
 	 * Read a formula in the given worksheet at the given cell location.
+	 * @return string|null an integer if the cell exists and contains a formula, `null` otherwise.
 	 * @throws XlsxFastEditorXmlException
 	 */
 	public function readFormula(): ?string
@@ -134,6 +135,7 @@ private function value(): ?string
 
 	/**
 	 * Read the float value of the cell.
+	 * @return float|null a float if the cell exists and contains a number, `null` otherwise.
 	 */
 	public function readFloat(): ?float
 	{
@@ -146,6 +148,7 @@ public function readFloat(): ?float
 
 	/**
 	 * Read the date/time value of the cell, if any.
+	 * @return \DateTimeImmutable|null a date if the cell exists and contains a number, `null` otherwise.
 	 * @throws XlsxFastEditorFileFormatException
 	 * @throws XlsxFastEditorXmlException
 	 */
@@ -165,6 +168,7 @@ public function readDateTime(): ?\DateTimeImmutable
 
 	/**
 	 * Read the integer value of the cell.
+	 * @return int|null an integer if the cell exists and contains a number, `null` otherwise.
 	 */
 	public function readInt(): ?int
 	{
@@ -176,8 +180,8 @@ public function readInt(): ?int
 	}
 
 	/**
-	 * Read the string value of the cell,
-	 * compatible with the shared string approach.
+	 * Read the string value of the cell, compatible with the shared string approach.
+	 * @return string|null a string if the cell exists and contains a value, `null` otherwise.
 	 * @throws XlsxFastEditorFileFormatException
 	 * @throws XlsxFastEditorXmlException
 	 */
@@ -202,6 +206,7 @@ public function readString(): ?string
 
 	/**
 	 * Read the hyperlink value of the cell, if any.
+	 * @return string|null a string if the cell exists and contains a hyperlink, `null` otherwise.
 	 * @throws XlsxFastEditorFileFormatException
 	 * @throws XlsxFastEditorXmlException
 	 */

src/XlsxFastEditorRow.php

@@ -49,7 +49,7 @@ private function getXPath(): \DOMXPath
 	}
 
 	/**
-	 * Access the previous existing row, if any, null otherwise.
+	 * Access the previous existing row, if any, `null` otherwise.
 	 */
 	public function getPreviousRow(): ?XlsxFastEditorRow
 	{
@@ -64,7 +64,7 @@ public function getPreviousRow(): ?XlsxFastEditorRow
 	}
 
 	/**
-	 * Access the next existing row, if any, null otherwise.
+	 * Access the next existing row, if any, `null` otherwise.
 	 */
 	public function getNextRow(): ?XlsxFastEditorRow
 	{
@@ -95,7 +95,7 @@ public function cellsIterator(): \Traversable
 
 	/**
 	 * Get the first existing cell for a given line.
-	 * @return XlsxFastEditorCell|null The first cell of the given line if it exists, null otherwise.
+	 * @return XlsxFastEditorCell|null The first cell of the given line if it exists, `null` otherwise.
 	 */
 	public function getFirstCell(): ?XlsxFastEditorCell
 	{
@@ -214,7 +214,7 @@ public function getCellAutocreate(string $cellName): XlsxFastEditorCell
 
 	/**
 	 * Get the last existing cell for a given line.
-	 * @return XlsxFastEditorCell|null The last cell of the given line if it exists, null otherwise.
+	 * @return XlsxFastEditorCell|null The last cell of the given line if it exists, `null` otherwise.
 	 */
 	public function getLastCell(): ?XlsxFastEditorCell
 	{