From 5828895eeccd622002c35508b4086f1e15440310 Mon Sep 17 00:00:00 2001
From: "Timothy J. Warren" <tim@timshomepage.net>
Date: Thu, 19 Oct 2023 12:20:11 -0400
Subject: [PATCH] Remove redundant docblock tags

---
 src/Editor.php      | 16 ----------
 src/FileType.php    |  8 +----
 src/Kilo.php        | 40 +++++--------------------
 src/Row.php         | 72 ++++-----------------------------------------
 src/Tokens/PHP8.php |  4 +--
 5 files changed, 17 insertions(+), 123 deletions(-)

diff --git a/src/Editor.php b/src/Editor.php
index 4e5821a..e20f0ae 100644
--- a/src/Editor.php
+++ b/src/Editor.php
@@ -68,10 +68,6 @@ class Editor {
 
 	/**
 	 * Create the Editor instance with CLI arguments
-	 *
-	 * @param int $argc
-	 * @param array $argv
-	 * @return Editor
 	 */
 	public static function new(int $argc = 0, array $argv = []): Editor
 	{
@@ -85,8 +81,6 @@ class Editor {
 
 	/**
 	 * The real constructor, ladies and gentlemen
-	 *
-	 * @param string|null $filename
 	 */
 	private function __construct(?string $filename = NULL)
 	{
@@ -145,8 +139,6 @@ class Editor {
 
 	/**
 	 * Set a status message to be displayed, using printf formatting
-	 * @param string $fmt
-	 * @param mixed ...$args
 	 */
 	public function setStatusMessage(string $fmt, mixed ...$args): void
 	{
@@ -163,10 +155,6 @@ class Editor {
 
 	/**
 	 * Cursor X to Render X
-	 *
-	 * @param Row $row
-	 * @param int $cx
-	 * @return int
 	 */
 	protected function rowCxToRx(Row $row, int $cx): int
 	{
@@ -185,10 +173,6 @@ class Editor {
 
 	/**
 	 * Render X to Cursor X
-	 *
-	 * @param Row $row
-	 * @param int $rx
-	 * @return int
 	 */
 	protected function rowRxToCx(Row $row, int $rx): int
 	{
diff --git a/src/FileType.php b/src/FileType.php
index ebea028..0154810 100644
--- a/src/FileType.php
+++ b/src/FileType.php
@@ -7,9 +7,6 @@ use Aviat\Kilo\Enum\SyntaxFamily;
 class FileType {
 	/**
 	 * Create the FileType object from the filename
-	 *
-	 * @param string|null $filename
-	 * @return self
 	 */
 	public static function from(?string $filename): self
 	{
@@ -20,9 +17,6 @@ class FileType {
 
 	/**
 	 * Create the Syntax object from the filename
-	 *
-	 * @param string $filename
-	 * @return Syntax
 	 */
 	private static function getSyntaxFromFilename(string $filename): Syntax
 	{
@@ -212,4 +206,4 @@ class FileType {
 	}
 
 	private function __construct(public string $name, public Syntax $syntax) {}
-}
\ No newline at end of file
+}
diff --git a/src/Kilo.php b/src/Kilo.php
index 9c93a65..c1b4c4e 100644
--- a/src/Kilo.php
+++ b/src/Kilo.php
@@ -24,9 +24,6 @@ const T_RAW = -1;
 
 /**
  * Configure syntax highlighting colors
- *
- * @param Highlight $hl
- * @return Color | Color256 | int
  */
 function get_syntax_color(Highlight $hl): Color | Color256 | int {
 	return match ($hl)
@@ -55,9 +52,6 @@ function get_syntax_color(Highlight $hl): Color | Color256 | int {
 /**
  * Do bit twiddling to convert a letter into
  * its Ctrl-letter equivalent ordinal ascii value
- *
- * @param string $char
- * @return int
  */
 function ctrl_key(string $char): int
 {
@@ -74,9 +68,6 @@ function ctrl_key(string $char): int
 
 /**
  * Does the one-character string contain an ascii ordinal value?
- *
- * @param string $single_char
- * @return bool
  */
 function is_ascii(string $single_char): bool
 {
@@ -90,9 +81,6 @@ function is_ascii(string $single_char): bool
 
 /**
  * Does the one-character string contain an ascii control character?
- *
- * @param string $char
- * @return bool
  */
 function is_ctrl(string $char): bool
 {
@@ -102,9 +90,6 @@ function is_ctrl(string $char): bool
 
 /**
  * Does the one-character string contain an ascii number?
- *
- * @param string $char
- * @return bool
  */
 function is_digit(string $char): bool
 {
@@ -114,9 +99,6 @@ function is_digit(string $char): bool
 
 /**
  * Does the one-character string contain ascii whitespace?
- *
- * @param string $char
- * @return bool
  */
 function is_space(string $char): bool
 {
@@ -138,9 +120,6 @@ function is_space(string $char): bool
 
 /**
  * Does the one-character string contain a character that separates tokens?
- *
- * @param string $char
- * @return bool
  */
 function is_separator(string $char): bool
 {
@@ -175,12 +154,7 @@ function array_replace_range(array &$array, int $offset, int $length, mixed $val
 }
 
 /**
- * Does the string $haystack contain $str, optionally searching from $offset?
- *
- * @param string $haystack
- * @param string $str
- * @param int|null $offset
- * @return bool
+ * Does the string $haystack contain $str, optionally searching from $offset
  */
 function str_has(string $haystack, string $str, ?int $offset = NULL): bool
 {
@@ -196,10 +170,6 @@ function str_has(string $haystack, string $str, ?int $offset = NULL): bool
 
 /**
  * Replace tabs with the specified number of spaces.
- *
- * @param string $str
- * @param int $number
- * @return string
  */
 function tabs_to_spaces(string $str, int $number = KILO_TAB_STOP): string
 {
@@ -227,11 +197,17 @@ function error_code_name(int $code): string
 	};
 }
 
+/**
+ * Adds two numbers to at most the $max value
+ */
 function saturating_add(int $a, int $b, int $max): int
 {
 	return ($a + $b > $max) ? $max : $a + $b;
 }
 
+/**
+ * Delete one number from another, down to zero at the least
+ */
 function saturating_sub(int $a, int $b): int
 {
 	if ($b > $a)
@@ -240,4 +216,4 @@ function saturating_sub(int $a, int $b): int
 	}
 
 	return $a - $b;
-}
\ No newline at end of file
+}
diff --git a/src/Row.php b/src/Row.php
index b8425eb..f28b848 100644
--- a/src/Row.php
+++ b/src/Row.php
@@ -28,11 +28,6 @@ class Row {
 
 	/**
 	 * Create a row in the current document
-	 *
-	 * @param Document $parent
-	 * @param string $chars
-	 * @param int $idx
-	 * @return self
 	 */
 	public static function new(Document $parent, string $chars, int $idx): self
 	{
@@ -45,8 +40,6 @@ class Row {
 
 	/**
 	 * Create an empty Row
-	 *
-	 * @return self
 	 */
 	public static function default(): self
 	{
@@ -74,6 +67,9 @@ class Row {
 		public int $idx,
 	) {}
 
+	/**
+	 * Set up dynamically generated properties
+	 */
 	public function __get(string $name): mixed
 	{
 		return match ($name)
@@ -87,8 +83,6 @@ class Row {
 
 	/**
 	 * Convert the row contents to a string for saving
-	 *
-	 * @return string
 	 */
 	public function __toString(): string
 	{
@@ -97,8 +91,6 @@ class Row {
 
 	/**
 	 * Set the properties to display for var_dump
-	 *
-	 * @return array
 	 */
 	public function __debugInfo(): array
 	{
@@ -114,8 +106,6 @@ class Row {
 
 	/**
 	 * Is this row a valid part of a document?
-	 *
-	 * @return bool
 	 */
 	public function isValid(): bool
 	{
@@ -125,8 +115,8 @@ class Row {
 	/**
 	 * Insert the string or character $c at index $at
 	 *
-	 * @param int $at
-	 * @param string $c
+	 * @param int $at The point to insert at
+	 * @param string $c The string to insert
 	 */
 	public function insert(int $at, string $c): void
 	{
@@ -143,8 +133,6 @@ class Row {
 
 	/**
 	 * Append $s to the current row
-	 *
-	 * @param string $s
 	 */
 	public function append(string $s): void
 	{
@@ -155,7 +143,7 @@ class Row {
 	/**
 	 * Delete the character at the specified index
 	 *
-	 * @param int $at
+	 * @param int $at The index to delete
 	 */
 	public function delete(int $at): void
 	{
@@ -170,8 +158,6 @@ class Row {
 
 	/**
 	 * Set the contents of the Row
-	 *
-	 * @param string $chars
 	 */
 	public function setChars(string $chars): void
 	{
@@ -279,10 +265,6 @@ class Row {
 
 	/**
 	 * Highlight number literals
-	 *
-	 * @param int $i
-	 * @param Syntax $opts
-	 * @return bool
 	 */
 	protected function highlightNumber(int &$i, Syntax $opts): bool
 	{
@@ -323,12 +305,6 @@ class Row {
 
 	/**
 	 * Highlight keywords and/or operators
-	 *
-	 * @param int $i
-	 * @param array $keywords
-	 * @param Highlight $syntaxType
-	 * @param bool $requireSeparator
-	 * @return bool
 	 */
 	protected function highlightWord(int &$i, array $keywords, Highlight $syntaxType, bool $requireSeparator = true): bool
 	{
@@ -362,11 +338,6 @@ class Row {
 
 	/**
 	 * Highlight a single-char character from a list of provided keywords
-	 *
-	 * @param int $i
-	 * @param array $chars
-	 * @param Highlight $syntaxType
-	 * @return bool
 	 */
 	protected function highlightChar(int &$i, array $chars, Highlight $syntaxType): bool
 	{
@@ -390,10 +361,6 @@ class Row {
 
 	/**
 	 * Highlight primary keywords
-	 *
-	 * @param int $i
-	 * @param Syntax $opts
-	 * @return bool
 	 */
 	protected function highlightPrimaryKeywords(int &$i, Syntax $opts): bool
 	{
@@ -402,10 +369,6 @@ class Row {
 
 	/**
 	 * Highlight secondary keywords
-	 *
-	 * @param int $i
-	 * @param Syntax $opts
-	 * @return bool
 	 */
 	protected function highlightSecondaryKeywords(int &$i, Syntax $opts): bool
 	{
@@ -414,10 +377,6 @@ class Row {
 
 	/**
 	 * Highlight language-specific operators
-	 *
-	 * @param int $i
-	 * @param Syntax $opts
-	 * @return bool
 	 */
 	protected function highlightOperators(int &$i, Syntax $opts): bool
 	{
@@ -426,10 +385,6 @@ class Row {
 
 	/**
 	 * Highlight common single-character operators
-	 *
-	 * @param int $i
-	 * @param Syntax $opts
-	 * @return bool
 	 */
 	protected function highlightCommonOperators(int &$i, Syntax $opts): bool
 	{
@@ -447,9 +402,6 @@ class Row {
 
 	/**
 	 * Highlight brackets and braces
-	 *
-	 * @param int $i
-	 * @return bool
 	 */
 	protected function highlightCommonDelimiters(int &$i): bool
 	{
@@ -462,10 +414,6 @@ class Row {
 
 	/**
 	 * Highlight character literals
-	 *
-	 * @param int $i
-	 * @param Syntax $opts
-	 * @return bool
 	 */
 	protected function highlightCharacter(int &$i, Syntax $opts): bool
 	{
@@ -501,10 +449,6 @@ class Row {
 
 	/**
 	 * Highlight single-line comments
-	 *
-	 * @param int $i
-	 * @param Syntax $opts
-	 * @return bool
 	 */
 	protected function highlightComment(int &$i, Syntax $opts): bool
 	{
@@ -529,10 +473,6 @@ class Row {
 
 	/**
 	 * Highlight quote-delimited string literals
-	 *
-	 * @param int $i
-	 * @param Syntax $opts
-	 * @return bool
 	 */
 	protected function highlightString(int &$i, Syntax $opts): bool
 	{
diff --git a/src/Tokens/PHP8.php b/src/Tokens/PHP8.php
index 6361ee9..137103b 100644
--- a/src/Tokens/PHP8.php
+++ b/src/Tokens/PHP8.php
@@ -13,7 +13,7 @@ class PHP8 extends PhpToken {
 	private array $tokens = [];
 
 	/**
-	 * Use 'token_get_all' to get the tokens for a file,
+	 * Use 'PhpToken' to get the tokens for a file,
 	 * organized by row number
 	 *
 	 * @param string $code
@@ -144,4 +144,4 @@ class PHP8 extends PhpToken {
 
 		return NULL;
 	}
-}
\ No newline at end of file
+}