From 2accf954cad76d1322341bc506bd6176fdd92b77 Mon Sep 17 00:00:00 2001
From: Reinier Criel <reinier.criel@gmail.com>
Date: Mon, 3 Nov 2025 10:20:05 -0800
Subject: [PATCH] Fix more documentation issues

---
 .../parsing/parsePackagesFromInstallArgs.js   | 26 +++++++++++++++----
 .../packagemanager/pip/utils/pipCommands.js   |  2 ++
 2 files changed, 23 insertions(+), 5 deletions(-)

diff --git a/packages/safe-chain/src/packagemanager/pip/parsing/parsePackagesFromInstallArgs.js b/packages/safe-chain/src/packagemanager/pip/parsing/parsePackagesFromInstallArgs.js
index 5ec0426..ee6f849 100644
--- a/packages/safe-chain/src/packagemanager/pip/parsing/parsePackagesFromInstallArgs.js
+++ b/packages/safe-chain/src/packagemanager/pip/parsing/parsePackagesFromInstallArgs.js
@@ -1,23 +1,37 @@
+/**
+ * @typedef {Object} PackageDetail
+ * @property {string} name
+ * @property {string} version
+ * @property {string} type
+ */
+
+/**
+ * @typedef {Object} PipOption
+ * @property {string} name
+ * @property {number} numberOfParameters
+ */
+
 /**
  * Supported formats that will be returned:
  * - package_name (no version)
  * - package_name==version (exact version)
  * - package_name===version (exact version, PEP 440)
- * 
- * "Ranges". Because they don't specify an exact version, the following formats are skipped and we will rely solely on the mitm scanner:
+ *
+ * Ranges: Because they don't specify an exact version, the following formats are skipped and we rely on the MITM scanner:
  * - package_name>=version
  * - package_name<=version
  * - package_name>version
  * - package_name<version
  * - package_name~=version
  * - package_name!=version
- * - git+https://... (VCS URLs - returned without version)
+ * - git+https://... (VCS URLs)
  * - -r requirements.txt (handled by flag skipping)
- */
-/**
+ *
  * @param {string[]} args
+ * @returns {PackageDetail[]}
  */
 export function parsePackagesFromInstallArgs(args) {
+  /** @type {PackageDetail[]} */
   const packages = [];
   let skipNext = false;
 
@@ -53,6 +67,7 @@ export function parsePackagesFromInstallArgs(args) {
 
 /**
  * @param {string} arg
+ * @returns {boolean}
  */
 function isPipOptionWithParameter(arg) {
 
@@ -108,6 +123,7 @@ function isPipOptionWithParameter(arg) {
 
 /**
  * @param {string} spec
+ * @returns {{ name: string, version: string } | null}
  */
 function parsePipSpec(spec) {
   // Ignore obvious URLs and paths, rely on mitm scanner
diff --git a/packages/safe-chain/src/packagemanager/pip/utils/pipCommands.js b/packages/safe-chain/src/packagemanager/pip/utils/pipCommands.js
index abda858..92699ac 100644
--- a/packages/safe-chain/src/packagemanager/pip/utils/pipCommands.js
+++ b/packages/safe-chain/src/packagemanager/pip/utils/pipCommands.js
@@ -4,6 +4,7 @@ export const pipWheelCommand = "wheel";
 
 /**
  * @param {string[]} args
+ * @returns {string | null}
  */
 export function getPipCommandForArgs(args) {
   if (!args || args.length === 0) {
@@ -22,6 +23,7 @@ export function getPipCommandForArgs(args) {
 
 /**
  * @param {string[]} args
+ * @returns {boolean}
  */
 export function hasDryRunArg(args) {
   return args.some((arg) => arg === "--dry-run");