From e93077c812ed8023e3aaf0eb817f238d041e6a7a Mon Sep 17 00:00:00 2001
From: Shreya Agarwal <www.shreyaagarwal.com@gmail.com>
Date: Thu, 4 Jul 2024 16:16:20 +0530
Subject: [PATCH 1/2] fix: fix multiline argument description parsing

---
 bin/command.php | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/bin/command.php b/bin/command.php
index c10f9ae1..5976d0b0 100644
--- a/bin/command.php
+++ b/bin/command.php
@@ -630,7 +630,9 @@ private static function parse_docblock( $docblock ) {
 					$key = key( $ret['parameters'][ $param_name ] );
 					reset( $ret['parameters'][ $param_name ] );
 					if ( ! empty( $ret['parameters'][ $param_name ][ $key ][2] )
-						&& '{' === substr( $ret['parameters'][ $param_name ][ $key ][2], -1 ) ) {
+						&&
+						in_array( substr( $ret['parameters'][ $param_name ][ $key ][2], -1 ), [ '{', ',' ], true )
+					) {
 						$in_param = [ $param_name, $key ];
 					}
 				}

From 179c09dd80ee60af51b85bf72225c87119a3f3cc Mon Sep 17 00:00:00 2001
From: Shreya Agarwal <www.shreyaagarwal.com@gmail.com>
Date: Tue, 16 Jul 2024 16:28:47 +0530
Subject: [PATCH 2/2] refactor: refined parsing logic

---
 bin/command.php                     | 36 +++++++++++++++++------------
 bin/templates/internal-api.mustache |  2 +-
 2 files changed, 22 insertions(+), 16 deletions(-)

diff --git a/bin/command.php b/bin/command.php
index 5976d0b0..6606b535 100644
--- a/bin/command.php
+++ b/bin/command.php
@@ -600,26 +600,36 @@ private static function get_simple_representation( $reflection ) {
 	 * @return array
 	 */
 	private static function parse_docblock( $docblock ) {
-		$ret        = [
+		$ret                          = [
 			'description' => '',
 			'parameters'  => [],
 		];
-		$extra_line = '';
-		$in_param   = false;
+		$extra_line                   = '';
+		$in_param                     = false;
+		$description_parsing_complete = false;
+
 		foreach ( preg_split( "/(\r?\n)/", $docblock ) as $line ) {
 			if ( preg_match( '/^(?=\s+?\*[^\/])(.+)/', $line, $matches ) ) {
 				$info = trim( $matches[1] );
 				$info = preg_replace( '/^(\*\s+?)/', '', $info );
-				if ( $in_param ) {
+
+				if ( '@' !== $info[0] && false === $description_parsing_complete ) {
+					$ret['description'] .= PHP_EOL . "{$extra_line}{$info}";
+					$extra_line          = '';
+					continue;
+				}
+
+				$description_parsing_complete = true;
+
+				if ( '@' !== $info[0] ) {
+					if ( false === $in_param ) {
+						continue;
+					}
 					list( $param_name, $key )                     = $in_param;
 					$ret['parameters'][ $param_name ][ $key ][2] .= PHP_EOL . $info;
-					if ( '}' === substr( $info, -1 ) ) {
-						$in_param = false;
-					}
-				} elseif ( '@' !== $info[0] ) {
-					$ret['description'] .= PHP_EOL . "{$extra_line}{$info}";
 				} else {
 					preg_match( '/@(\w+)/', $info, $matches );
+					error_log( print_r( $info, true ) );
 					$param_name = $matches[1];
 					$value      = str_replace( "@$param_name ", '', $info );
 					if ( ! isset( $ret['parameters'][ $param_name ] ) ) {
@@ -629,13 +639,9 @@ private static function parse_docblock( $docblock ) {
 					end( $ret['parameters'][ $param_name ] );
 					$key = key( $ret['parameters'][ $param_name ] );
 					reset( $ret['parameters'][ $param_name ] );
-					if ( ! empty( $ret['parameters'][ $param_name ][ $key ][2] )
-						&&
-						in_array( substr( $ret['parameters'][ $param_name ][ $key ][2], -1 ), [ '{', ',' ], true )
-					) {
-						$in_param = [ $param_name, $key ];
-					}
 				}
+
+				$in_param   = [ $param_name, $key ];
 				$extra_line = '';
 			} else {
 				$extra_line .= PHP_EOL;
diff --git a/bin/templates/internal-api.mustache b/bin/templates/internal-api.mustache
index 8e02417a..457262ac 100644
--- a/bin/templates/internal-api.mustache
+++ b/bin/templates/internal-api.mustache
@@ -13,7 +13,7 @@
 <strong>{{1}}</strong> ({{0}}) {{{2}}}<br />
 {{/phpdoc.parameters.param}}
 {{#phpdoc.parameters.return}}
-<strong>@return</strong> ({{0}}) {{2}}<br />
+<strong>@return</strong> ({{0}}) {{{2}}}<br />
 {{/phpdoc.parameters.return}}
 </div>