From 3d4a0cadc950d4440251efa11b55b0bfb0afdef7 Mon Sep 17 00:00:00 2001
From: nsfisis <nsfisis@gmail.com>
Date: Thu, 6 Aug 2026 04:22:46 +0900
Subject: chore: drop @param/@return tags that only restate Rust types

The ported docblocks copied @param and @return straight from the PHP
source. When such a tag carries nothing but a type and an argument name,
the Rust signature already states it, so the line is noise. Tags whose
text adds prose beyond the type are kept.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 crates/shirabe/src/util/auth_helper.rs          |  3 ---
 crates/shirabe/src/util/git.rs                  | 11 -----------
 crates/shirabe/src/util/http/curl_downloader.rs |  4 ----
 crates/shirabe/src/util/http_downloader.rs      |  6 ------
 crates/shirabe/src/util/no_proxy_pattern.rs     |  2 --
 crates/shirabe/src/util/perforce.rs             | 15 ---------------
 crates/shirabe/src/util/platform.rs             |  5 -----
 crates/shirabe/src/util/process_executor.rs     |  3 ---
 crates/shirabe/src/util/svn.rs                  |  7 -------
 9 files changed, 56 deletions(-)

(limited to 'crates/shirabe/src/util')

diff --git a/crates/shirabe/src/util/auth_helper.rs b/crates/shirabe/src/util/auth_helper.rs
index 2131a107..0e02e764 100644
--- a/crates/shirabe/src/util/auth_helper.rs
+++ b/crates/shirabe/src/util/auth_helper.rs
@@ -52,7 +52,6 @@ impl AuthHelper {
         }
     }
 
-    /// @param 'prompt'|bool $storeAuth
     pub fn store_auth(&self, origin: &str, store_auth: StoreAuth) -> anyhow::Result<()> {
         let mut store: Option<()> = None;
         let mut config = self.config.borrow_mut();
@@ -443,8 +442,6 @@ impl AuthHelper {
         })
     }
 
-    /// @param array<string, mixed> $options
-    ///
     /// @return array<string, mixed> updated options
     pub fn add_authentication_options(
         &mut self,
diff --git a/crates/shirabe/src/util/git.rs b/crates/shirabe/src/util/git.rs
index 1c3474ea..cbda0d43 100644
--- a/crates/shirabe/src/util/git.rs
+++ b/crates/shirabe/src/util/git.rs
@@ -95,7 +95,6 @@ impl Git {
     ///
     /// As soon as a single command fails it will halt, so assume the commands are run as && in bash
     ///
-    /// @param non-empty-array<non-empty-list<string>> $commands
     /// @param mixed $commandOutput  the output will be written into this var if passed by ref
     ///                              if a callable is passed it will be used as output handler
     pub fn run_commands(
@@ -141,7 +140,6 @@ impl Git {
         self.run_command(command_callable, url, cwd, initial_clone, command_output)
     }
 
-    /// @param callable|array<callable> $commandCallable
     /// @param mixed       $commandOutput  the output will be written into this var if passed by ref
     ///                                    if a callable is passed it will be used as output handler
     fn run_command(
@@ -994,7 +992,6 @@ impl Git {
         String::new()
     }
 
-    /// @return list<string>
     pub fn get_no_show_signature_flags(
         process: &std::rc::Rc<std::cell::RefCell<ProcessExecutor>>,
     ) -> Vec<String> {
@@ -1023,7 +1020,6 @@ impl Git {
     ///
     /// @internal
     /// @param list<string> $arguments Additional arguments for git rev-list
-    /// @return non-empty-list<string>
     pub fn build_rev_list_command(
         process: &std::rc::Rc<std::cell::RefCell<ProcessExecutor>>,
         arguments: Vec<String>,
@@ -1091,7 +1087,6 @@ impl Git {
         Ok(false)
     }
 
-    /// @return array<int, string>|null
     fn get_authentication_failure(&self, url: &str) -> Option<IndexMap<CaptureKey, String>> {
         let mut m: IndexMap<CaptureKey, String> = IndexMap::new();
         if !Preg::is_match3(
@@ -1249,7 +1244,6 @@ impl Git {
         Platform::clear_env("DYLD_LIBRARY_PATH");
     }
 
-    /// @return non-empty-string
     pub fn get_github_domains_regex(config: &Config) -> String {
         let domains: Vec<String> = match config.get("github-domains") {
             PhpMixed::List(l) => l
@@ -1262,7 +1256,6 @@ impl Git {
         format!("({})", implode("|", &escaped))
     }
 
-    /// @return non-empty-string
     pub fn get_gitlab_domains_regex(config: &Config) -> String {
         let domains: Vec<String> = match config.get("gitlab-domains") {
             PhpMixed::List(l) => l
@@ -1275,9 +1268,6 @@ impl Git {
         format!("({})", implode("|", &escaped))
     }
 
-    /// @param non-empty-string $message
-    ///
-    /// @return never
     fn throw_exception(&mut self, message: &str, url: &str) -> anyhow::Result<()> {
         // git might delete a directory when it fails and php will not know
         clearstatcache();
@@ -1352,7 +1342,6 @@ impl Git {
         *VERSION.lock().unwrap() = Some(version);
     }
 
-    /// @param string[] $credentials
     fn mask_credentials(&self, error: &str, credentials: &[String]) -> String {
         let mut masked_credentials: Vec<String> = vec![];
 
diff --git a/crates/shirabe/src/util/http/curl_downloader.rs b/crates/shirabe/src/util/http/curl_downloader.rs
index 1207dea0..2d2259b9 100644
--- a/crates/shirabe/src/util/http/curl_downloader.rs
+++ b/crates/shirabe/src/util/http/curl_downloader.rs
@@ -63,7 +63,6 @@ enum Decision {
 }
 
 impl CurlDownloader {
-    /// @param mixed[] $options
     pub fn new(
         io: std::rc::Rc<std::cell::RefCell<dyn IOInterface>>,
         config: std::rc::Rc<std::cell::RefCell<Config>>,
@@ -100,9 +99,6 @@ impl CurlDownloader {
         }
     }
 
-    /// @param mixed[]  $options
-    /// @param non-empty-string $url
-    ///
     /// Runs the request through the redirect/retry/status state machine until it resolves,
     /// mirroring what the PHP promise resolver + `tick()` loop used to do together.
     pub async fn download(
diff --git a/crates/shirabe/src/util/http_downloader.rs b/crates/shirabe/src/util/http_downloader.rs
index 2346c351..b60664da 100644
--- a/crates/shirabe/src/util/http_downloader.rs
+++ b/crates/shirabe/src/util/http_downloader.rs
@@ -191,8 +191,6 @@ impl HttpDownloader {
         self.execute(url, options, Some(to), false).await
     }
 
-    /// @phpstan-param non-empty-string $url
-    ///
     /// Shared core of `get`/`add`/`copy`/`add_copy`: mock short-circuit, empty-URL guard, the
     /// sync/allow_async gate, and the concurrency-limiting semaphore permit. Mirrors PHP `addJob`
     /// up to (but not including) the resolver, which is `dispatch`.
@@ -366,8 +364,6 @@ impl HttpDownloader {
     }
 
     /// @internal
-    ///
-    /// @param  array{warning?: string, info?: string, warning-versions?: string, info-versions?: string, warnings?: array<array{versions: string, message: string}>, infos?: array<array{versions: string, message: string}>} $data
     pub fn output_warnings(
         io: std::rc::Rc<std::cell::RefCell<dyn IOInterface>>,
         url: &str,
@@ -466,8 +462,6 @@ impl HttpDownloader {
     }
 
     /// @internal
-    ///
-    /// @return ?string[]
     pub fn get_exception_hints(e: &anyhow::Error) -> Option<Vec<String>> {
         let e_as_transport: Option<&TransportException> = e.downcast_ref::<TransportException>();
         e_as_transport?;
diff --git a/crates/shirabe/src/util/no_proxy_pattern.rs b/crates/shirabe/src/util/no_proxy_pattern.rs
index 5ece7942..582fdb68 100644
--- a/crates/shirabe/src/util/no_proxy_pattern.rs
+++ b/crates/shirabe/src/util/no_proxy_pattern.rs
@@ -69,8 +69,6 @@ impl NoProxyPattern {
     }
 
     /// Returns false is the url cannot be parsed, otherwise a data object
-    ///
-    /// @return bool|stdClass
     pub(crate) fn get_url_data(&self, url: &str) -> anyhow::Result<Option<UrlData>> {
         let host = parse_url(url, PHP_URL_HOST);
         if empty(&host) {
diff --git a/crates/shirabe/src/util/perforce.rs b/crates/shirabe/src/util/perforce.rs
index e2591301..ac455fc7 100644
--- a/crates/shirabe/src/util/perforce.rs
+++ b/crates/shirabe/src/util/perforce.rs
@@ -37,7 +37,6 @@ pub struct Perforce {
 }
 
 impl Perforce {
-    /// @phpstan-param RepoConfig $repoConfig
     pub fn new(
         repo_config: IndexMap<String, PhpMixed>,
         port: String,
@@ -69,7 +68,6 @@ impl Perforce {
         this
     }
 
-    /// @phpstan-param RepoConfig $repoConfig
     pub fn create(
         repo_config: IndexMap<String, PhpMixed>,
         port: String,
@@ -95,7 +93,6 @@ impl Perforce {
         ) == 0
     }
 
-    /// @phpstan-param RepoConfig $repoConfig
     pub fn initialize(&mut self, repo_config: &IndexMap<String, PhpMixed>) {
         self.unique_perforce_client_name = self.generate_unique_perforce_client_name();
         if repo_config.is_empty() {
@@ -133,7 +130,6 @@ impl Perforce {
         }
     }
 
-    /// @return non-empty-string
     pub fn generate_unique_perforce_client_name(&self) -> String {
         format!("{}_{}", gethostname(), time())
     }
@@ -151,7 +147,6 @@ impl Perforce {
         file_system.borrow_mut().remove(&client_spec);
     }
 
-    /// @param non-empty-string|non-empty-list<string> $command
     pub(crate) fn execute_command(&mut self, command: PhpMixed) -> i64 {
         self.command_result = String::new();
 
@@ -239,7 +234,6 @@ impl Perforce {
         }
     }
 
-    /// @return non-empty-string
     pub fn get_p4_client_spec(&mut self) -> String {
         let path = self.path.clone();
         format!("{}/{}.p4.spec", path, self.get_client())
@@ -333,7 +327,6 @@ impl Perforce {
 
     /// @internal
     /// @param non-empty-list<string> $arguments Additional arguments for git rev-list
-    /// @return non-empty-list<string>
     pub fn generate_p4_command(&mut self, arguments: Vec<String>, use_client: bool) -> Vec<String> {
         let mut p4_command: Vec<String> = vec![Self::get_p4_executable()];
         if self.get_user().is_some() {
@@ -415,7 +408,6 @@ impl Perforce {
         Ok(())
     }
 
-    /// @param resource|false $spec
     pub fn write_client_spec_to_file(&mut self, spec: &PhpResource) {
         fwrite(
             spec,
@@ -527,8 +519,6 @@ impl Perforce {
         Ok(())
     }
 
-    /// @param resource $pipe
-    /// @param mixed    $name
     pub(crate) fn read(&self, pipe: &PhpResource, _name: PhpMixed) {
         if feof(pipe) {
             return;
@@ -590,7 +580,6 @@ impl Perforce {
         Ok(())
     }
 
-    /// @return mixed[]|null
     pub fn get_composer_information(
         &mut self,
         identifier: &str,
@@ -663,7 +652,6 @@ impl Perforce {
         None
     }
 
-    /// @return array{master: string}
     pub fn get_branches(&mut self) -> IndexMap<String, String> {
         let mut possible_branches: IndexMap<String, String> = IndexMap::new();
         if !self.is_stream() {
@@ -725,7 +713,6 @@ impl Perforce {
         result
     }
 
-    /// @return array<string, string>
     pub fn get_tags(&mut self) -> IndexMap<String, String> {
         let command = self.generate_p4_command(vec!["labels".to_string()], true);
         self.execute_command(PhpMixed::List(
@@ -771,7 +758,6 @@ impl Perforce {
         false
     }
 
-    /// @return mixed|null
     pub(crate) fn get_change_list(&mut self, reference: &str) -> Option<String> {
         let index = strpos(reference, "@")?;
         let label = substr(reference, index as i64, None);
@@ -789,7 +775,6 @@ impl Perforce {
         Some(fields.get(1).cloned().unwrap_or_default())
     }
 
-    /// @return mixed|null
     pub fn get_commit_logs(&mut self, from_reference: &str, to_reference: &str) -> Option<String> {
         let from_change_list = self.get_change_list(from_reference)?;
         let to_change_list = self.get_change_list(to_reference)?;
diff --git a/crates/shirabe/src/util/platform.rs b/crates/shirabe/src/util/platform.rs
index 259d5c95..7b1c8f61 100644
--- a/crates/shirabe/src/util/platform.rs
+++ b/crates/shirabe/src/util/platform.rs
@@ -58,10 +58,6 @@ impl Platform {
     }
 
     /// getenv() equivalent but reads from the runtime global variables first
-    ///
-    /// @param non-empty-string $name
-    ///
-    /// @return string|false
     pub fn get_env(name: &str) -> Option<String> {
         if let Some(value) = PHP_SERVER.lock().unwrap().get(name) {
             return Some(value.to_string_lossy().into_owned());
@@ -388,7 +384,6 @@ impl Platform {
         cached.unwrap_or(false)
     }
 
-    /// @return 'NUL'|'/dev/null'
     pub fn get_dev_null() -> String {
         if Self::is_windows() {
             return "NUL".to_string();
diff --git a/crates/shirabe/src/util/process_executor.rs b/crates/shirabe/src/util/process_executor.rs
index 9e89bdd4..c24e2f83 100644
--- a/crates/shirabe/src/util/process_executor.rs
+++ b/crates/shirabe/src/util/process_executor.rs
@@ -790,7 +790,6 @@ impl ProcessExecutor {
         self.allow_async = true;
     }
 
-    /// @return string[]
     pub fn split_lines(&self, output: &str) -> Vec<String> {
         let output = trim(output, None);
 
@@ -821,7 +820,6 @@ impl ProcessExecutor {
         Self::escape_argument(argument)
     }
 
-    /// @param string|list<string> $command
     fn output_command_run(&self, command: &PhpMixed, cwd: Option<&str>, r#async: bool) {
         Self::output_command_run_with(&self.io, command, cwd, r#async);
     }
@@ -943,7 +941,6 @@ impl ProcessExecutor {
         argument
     }
 
-    /// @param string[]|string $command
     pub fn requires_git_dir_env(&self, command: &PhpMixed) -> bool {
         let cmd: Vec<String> = if !is_array(command) {
             explode(" ", command.as_string().unwrap_or(""))
diff --git a/crates/shirabe/src/util/svn.rs b/crates/shirabe/src/util/svn.rs
index 50315316..a2974760 100644
--- a/crates/shirabe/src/util/svn.rs
+++ b/crates/shirabe/src/util/svn.rs
@@ -124,7 +124,6 @@ impl Svn {
             .map(|o| o.unwrap_or_default())
     }
 
-    /// @param non-empty-list<string> $svnCommand
     fn execute_with_auth_retry(
         &mut self,
         svn_command: Vec<String>,
@@ -257,8 +256,6 @@ impl Svn {
     /// @param non-empty-list<string> $cmd  Usually 'svn ls' or something like that.
     /// @param string $url  Repo URL.
     /// @param string $path Target for a checkout
-    ///
-    /// @return non-empty-list<string>
     pub(crate) fn get_command(
         &mut self,
         mut cmd: Vec<String>,
@@ -280,8 +277,6 @@ impl Svn {
     /// Return the credential string for the svn command.
     ///
     /// Adds --no-auth-cache when credentials are present.
-    ///
-    /// @return list<string>
     pub(crate) fn get_credential_args(&mut self) -> Vec<String> {
         if !self.has_auth() {
             return vec![];
@@ -354,8 +349,6 @@ impl Svn {
     }
 
     /// Return the no-auth-cache switch.
-    ///
-    /// @return list<string>
     pub(crate) fn get_auth_cache_args(&self) -> Vec<String> {
         if self.cache_credentials {
             vec![]
-- 
cgit v1.3.1