chore: add additional php doc tags

stainless-app[bot] · stainless-app[bot] · commit 3a18c70daa9f · 2025-08-29T02:51:04.000Z
diff --git a/.gitignore b/.gitignore
@@ -1,11 +1,11 @@
-*.swo
-*.swp
+composer.lock
+docs/
 .idea/
 .php-cs-fixer.cache
 .php-cs-fixer.php
-.phpdoc/
 .phpunit.cache
-composer.lock
 phpunit.xml
 playground/
+*.swo
+*.swp
 vendor/
diff --git a/composer.json b/composer.json
@@ -44,6 +44,7 @@
     "symfony/http-client": "^7"
   },
   "scripts": {
+    "build:docs": "curl --etag-save ./vendor/ag.etags --etag-compare ./vendor/ag.etags --create-dirs --remote-name --output-dir ./vendor/bin --no-progress-meter -- https://github.com/ApiGen/ApiGen/releases/latest/download/apigen.phar && php ./vendor/bin/apigen.phar --output docs -- src",
     "lint": "./scripts/lint",
     "test": "./scripts/test"
   }
diff --git a/src/Client.php b/src/Client.php
@@ -19,22 +19,49 @@ class Client extends BaseClient
 {
     public string $apiKey;
 
+    /**
+     * @api
+     */
     public SmartscraperService $smartscraper;
 
+    /**
+     * @api
+     */
     public MarkdownifyService $markdownify;
 
+    /**
+     * @api
+     */
     public SearchscraperService $searchscraper;
 
+    /**
+     * @api
+     */
     public GenerateSchemaService $generateSchema;
 
+    /**
+     * @api
+     */
     public CrawlService $crawl;
 
+    /**
+     * @api
+     */
     public CreditsService $credits;
 
+    /**
+     * @api
+     */
     public ValidateService $validate;
 
+    /**
+     * @api
+     */
     public FeedbackService $feedback;
 
+    /**
+     * @api
+     */
     public HealthzService $healthz;
 
     public function __construct(?string $apiKey = null, ?string $baseUrl = null)
diff --git a/src/Core/ServiceContracts/CrawlContract.php b/src/Core/ServiceContracts/CrawlContract.php
@@ -13,12 +13,17 @@
 
 interface CrawlContract
 {
+    /**
+     * @api
+     */
     public function retrieveResults(
         string $taskID,
         ?RequestOptions $requestOptions = null
     ): CrawlGetResultsResponse;
 
     /**
+     * @api
+     *
      * @param string $url Starting URL for crawling
      * @param int $depth Maximum crawl depth from starting URL
      * @param bool $extractionMode Use AI extraction (true) or markdown conversion (false)
diff --git a/src/Core/ServiceContracts/CreditsContract.php b/src/Core/ServiceContracts/CreditsContract.php
@@ -9,6 +9,9 @@
 
 interface CreditsContract
 {
+    /**
+     * @api
+     */
     public function retrieve(
         ?RequestOptions $requestOptions = null
     ): CreditGetResponse;
diff --git a/src/Core/ServiceContracts/FeedbackContract.php b/src/Core/ServiceContracts/FeedbackContract.php
@@ -12,6 +12,8 @@
 interface FeedbackContract
 {
     /**
+     * @api
+     *
      * @param int $rating Rating score
      * @param string $requestID Request to provide feedback for
      * @param string|null $feedbackText Optional feedback comments
diff --git a/src/Core/ServiceContracts/GenerateSchemaContract.php b/src/Core/ServiceContracts/GenerateSchemaContract.php
@@ -14,6 +14,8 @@
 interface GenerateSchemaContract
 {
     /**
+     * @api
+     *
      * @param string $userPrompt Natural language description of desired schema
      * @param mixed $existingSchema Existing schema to modify or extend
      */
@@ -23,6 +25,9 @@ public function create(
         ?RequestOptions $requestOptions = null,
     ): GenerateSchemaNewResponse;
 
+    /**
+     * @api
+     */
     public function retrieve(
         string $requestID,
         ?RequestOptions $requestOptions = null
diff --git a/src/Core/ServiceContracts/HealthzContract.php b/src/Core/ServiceContracts/HealthzContract.php
@@ -9,6 +9,9 @@
 
 interface HealthzContract
 {
+    /**
+     * @api
+     */
     public function check(
         ?RequestOptions $requestOptions = null
     ): HealthzCheckResponse;
diff --git a/src/Core/ServiceContracts/MarkdownifyContract.php b/src/Core/ServiceContracts/MarkdownifyContract.php
@@ -13,6 +13,8 @@
 interface MarkdownifyContract
 {
     /**
+     * @api
+     *
      * @param string $websiteURL URL to convert to markdown
      * @param array<string, string> $headers
      * @param list<string> $steps Interaction steps before conversion
@@ -24,6 +26,9 @@ public function convert(
         ?RequestOptions $requestOptions = null,
     ): CompletedMarkdownify;
 
+    /**
+     * @api
+     */
     public function retrieveStatus(
         string $requestID,
         ?RequestOptions $requestOptions = null
diff --git a/src/Core/ServiceContracts/SearchscraperContract.php b/src/Core/ServiceContracts/SearchscraperContract.php
@@ -13,6 +13,8 @@
 interface SearchscraperContract
 {
     /**
+     * @api
+     *
      * @param string $userPrompt Search query and extraction instruction
      * @param array<string, string> $headers
      * @param int $numResults Number of websites to scrape from search results
@@ -26,6 +28,9 @@ public function create(
         ?RequestOptions $requestOptions = null,
     ): CompletedSearchScraper;
 
+    /**
+     * @api
+     */
     public function retrieveStatus(
         string $requestID,
         ?RequestOptions $requestOptions = null
diff --git a/src/Core/ServiceContracts/SmartscraperContract.php b/src/Core/ServiceContracts/SmartscraperContract.php
@@ -13,6 +13,8 @@
 interface SmartscraperContract
 {
     /**
+     * @api
+     *
      * @param string $userPrompt Extraction instruction for the LLM
      * @param array<string, string> $cookies Cookies to include in the request
      * @param array<string, string> $headers HTTP headers to include in the request
@@ -38,11 +40,17 @@ public function create(
         ?RequestOptions $requestOptions = null,
     ): CompletedSmartscraper;
 
+    /**
+     * @api
+     */
     public function retrieve(
         string $requestID,
         ?RequestOptions $requestOptions = null
     ): CompletedSmartscraper|FailedSmartscraper;
 
+    /**
+     * @api
+     */
     public function list(
         ?RequestOptions $requestOptions = null
     ): CompletedSmartscraper|FailedSmartscraper;
diff --git a/src/Core/ServiceContracts/ValidateContract.php b/src/Core/ServiceContracts/ValidateContract.php
@@ -9,6 +9,9 @@
 
 interface ValidateContract
 {
+    /**
+     * @api
+     */
     public function apiKey(
         ?RequestOptions $requestOptions = null
     ): ValidateAPIKeyResponse;
diff --git a/src/Core/Services/CrawlService.php b/src/Core/Services/CrawlService.php
@@ -19,7 +19,9 @@ final class CrawlService implements CrawlContract
     public function __construct(private Client $client) {}
 
     /**
-     * Retrieve the status and results of a crawling job.
+     * @api
+     *
+     * Retrieve the status and results of a crawling job
      */
     public function retrieveResults(
         string $taskID,
@@ -35,6 +37,8 @@ public function retrieveResults(
     }
 
     /**
+     * @api
+     *
      * Initiate comprehensive website crawling with sitemap support.
      * Supports both AI extraction mode and markdown conversion mode.
      * Returns a task ID for async processing.
diff --git a/src/Core/Services/CreditsService.php b/src/Core/Services/CreditsService.php
@@ -14,7 +14,9 @@ final class CreditsService implements CreditsContract
     public function __construct(private Client $client) {}
 
     /**
-     * Retrieve the current credit balance and usage for the authenticated user.
+     * @api
+     *
+     * Retrieve the current credit balance and usage for the authenticated user
      */
     public function retrieve(
         ?RequestOptions $requestOptions = null
diff --git a/src/Core/Services/FeedbackService.php b/src/Core/Services/FeedbackService.php
@@ -17,7 +17,9 @@ final class FeedbackService implements FeedbackContract
     public function __construct(private Client $client) {}
 
     /**
-     * Submit feedback for a specific request.
+     * @api
+     *
+     * Submit feedback for a specific request
      *
      * @param int $rating Rating score
      * @param string $requestID Request to provide feedback for
diff --git a/src/Core/Services/GenerateSchemaService.php b/src/Core/Services/GenerateSchemaService.php
@@ -20,6 +20,8 @@ final class GenerateSchemaService implements GenerateSchemaContract
     public function __construct(private Client $client) {}
 
     /**
+     * @api
+     *
      * Generate or modify JSON schemas based on natural language descriptions.
      * Can create new schemas or extend existing ones.
      *
@@ -47,7 +49,9 @@ public function create(
     }
 
     /**
-     * Retrieve the status and results of a schema generation request.
+     * @api
+     *
+     * Retrieve the status and results of a schema generation request
      */
     public function retrieve(
         string $requestID,
diff --git a/src/Core/Services/HealthzService.php b/src/Core/Services/HealthzService.php
@@ -14,7 +14,9 @@ final class HealthzService implements HealthzContract
     public function __construct(private Client $client) {}
 
     /**
-     * Check the health status of the service.
+     * @api
+     *
+     * Check the health status of the service
      */
     public function check(
         ?RequestOptions $requestOptions = null
diff --git a/src/Core/Services/MarkdownifyService.php b/src/Core/Services/MarkdownifyService.php
@@ -19,7 +19,9 @@ final class MarkdownifyService implements MarkdownifyContract
     public function __construct(private Client $client) {}
 
     /**
-     * Convert web page content to clean Markdown format.
+     * @api
+     *
+     * Convert web page content to clean Markdown format
      *
      * @param string $websiteURL URL to convert to markdown
      * @param array<string, string> $headers
@@ -47,7 +49,9 @@ public function convert(
     }
 
     /**
-     * Retrieve the status and results of a markdown conversion.
+     * @api
+     *
+     * Retrieve the status and results of a markdown conversion
      */
     public function retrieveStatus(
         string $requestID,
diff --git a/src/Core/Services/SearchscraperService.php b/src/Core/Services/SearchscraperService.php
@@ -19,6 +19,8 @@ final class SearchscraperService implements SearchscraperContract
     public function __construct(private Client $client) {}
 
     /**
+     * @api
+     *
      * Performs web search, selects relevant URLs, and extracts structured data from multiple websites.
      * Uses LLM to refine search queries and merge results from different sources.
      *
@@ -55,7 +57,9 @@ public function create(
     }
 
     /**
-     * Retrieve the status and results of a search scraping operation.
+     * @api
+     *
+     * Retrieve the status and results of a search scraping operation
      */
     public function retrieveStatus(
         string $requestID,
diff --git a/src/Core/Services/SmartscraperService.php b/src/Core/Services/SmartscraperService.php
@@ -20,6 +20,8 @@ final class SmartscraperService implements SmartscraperContract
     public function __construct(private Client $client) {}
 
     /**
+     * @api
+     *
      * Main scraping endpoint with LLM-powered content analysis. Supports various fetching providers,
      * infinite scrolling, pagination, and custom output schemas.
      *
@@ -74,7 +76,9 @@ public function create(
     }
 
     /**
-     * Retrieve the status and results of a scraping operation.
+     * @api
+     *
+     * Retrieve the status and results of a scraping operation
      */
     public function retrieve(
         string $requestID,
@@ -90,7 +94,9 @@ public function retrieve(
     }
 
     /**
-     * Retrieve the status and results of a scraping operation.
+     * @api
+     *
+     * Retrieve the status and results of a scraping operation
      */
     public function list(
         ?RequestOptions $requestOptions = null
diff --git a/src/Core/Services/ValidateService.php b/src/Core/Services/ValidateService.php
@@ -14,7 +14,9 @@ final class ValidateService implements ValidateContract
     public function __construct(private Client $client) {}
 
     /**
-     * Validate the API key and retrieve associated user email.
+     * @api
+     *
+     * Validate the API key and retrieve associated user email
      */
     public function apiKey(
         ?RequestOptions $requestOptions = null
diff --git a/src/Crawl/CrawlStartParams.php b/src/Crawl/CrawlStartParams.php
@@ -15,6 +15,8 @@
  * Supports both AI extraction mode and markdown conversion mode.
  * Returns a task ID for async processing.
  *
+ * @see Scrapegraphai\Crawl->start
+ *
  * @phpstan-type crawl_start_params = array{
  *   url: string,
  *   depth?: int,
diff --git a/src/Feedback/FeedbackSubmitParams.php b/src/Feedback/FeedbackSubmitParams.php
@@ -12,6 +12,8 @@
 /**
  * Submit feedback for a specific request.
  *
+ * @see Scrapegraphai\Feedback->submit
+ *
  * @phpstan-type feedback_submit_params = array{
  *   rating: int, requestID: string, feedbackText?: string|null
  * }
diff --git a/src/GenerateSchema/GenerateSchemaCreateParams.php b/src/GenerateSchema/GenerateSchemaCreateParams.php
@@ -13,6 +13,8 @@
  * Generate or modify JSON schemas based on natural language descriptions.
  * Can create new schemas or extend existing ones.
  *
+ * @see Scrapegraphai\GenerateSchema->create
+ *
  * @phpstan-type generate_schema_create_params = array{
  *   userPrompt: string, existingSchema?: mixed
  * }
diff --git a/src/Markdownify/MarkdownifyConvertParams.php b/src/Markdownify/MarkdownifyConvertParams.php
diff --git a/src/Searchscraper/SearchscraperCreateParams.php b/src/Searchscraper/SearchscraperCreateParams.php
diff --git a/src/Smartscraper/SmartscraperCreateParams.php b/src/Smartscraper/SmartscraperCreateParams.php

Original file line number	Diff line number	Diff line change
`@@ -44,6 +44,7 @@`
`44`	`44`	`"symfony/http-client": "^7"`
`45`	`45`	`},`
`46`	`46`	`"scripts": {`
	`47`	`+ "build:docs": "curl --etag-save ./vendor/ag.etags --etag-compare ./vendor/ag.etags --create-dirs --remote-name --output-dir ./vendor/bin --no-progress-meter -- https://github.com/ApiGen/ApiGen/releases/latest/download/apigen.phar && php ./vendor/bin/apigen.phar --output docs -- src",`
`47`	`48`	`"lint": "./scripts/lint",`
`48`	`49`	`"test": "./scripts/test"`
`49`	`50`	`}`
Original file line number	Diff line number	Diff line change
`@@ -9,6 +9,9 @@`
`9`	`9`
`10`	`10`	`interface CreditsContract`
`11`	`11`	`{`
	`12`	`+ /**`
	`13`	`+ * @api`
	`14`	`+ */`
`12`	`15`	`public function retrieve(`
`13`	`16`	`?RequestOptions $requestOptions = null`
`14`	`17`	`): CreditGetResponse;`
Original file line number	Diff line number	Diff line change
`@@ -12,6 +12,8 @@`
`12`	`12`	`interface FeedbackContract`
`13`	`13`	`{`
`14`	`14`	`/**`
	`15`	`+ * @api`
	`16`	`+ *`
`15`	`17`	`* @param int $rating Rating score`
`16`	`18`	`* @param string $requestID Request to provide feedback for`
`17`	`19`	`* @param string\|null $feedbackText Optional feedback comments`