feat(slb-495): docblock comments updates on services

packages/drupal/silverback_ai/modules/silverback_ai_import/silverback_ai_import.module

@@ -15,8 +15,6 @@ use Drupal\silverback_ai_import\ContentImportAiService;
 function silverback_ai_import_form_alter(&$form, &$form_state, $form_id) {
   // @todo
   //$logger = Drupal::service('silverback_ai_imoprt.logger');
-  //dpm($logger->getEntries());
-
 }
 
 /**
@@ -122,7 +120,10 @@ function silverback_ai_import_form_node_page_split_form_alter(&$form, FormStateI
 }
 
 /**
- * {@inheritdoc}
+ * @param array $form
+ * @param \Drupal\Core\Form\FormStateInterface $form_state
+ *
+ * @return void
  */
 function _silverback_ai_import_form_submit_validate(array $form, FormStateInterface $form_state) {
   // @todo
@@ -143,7 +144,10 @@ function _silverback_ai_import_form_submit_validate(array $form, FormStateInterf
 }
 
 /**
- * {@inheritdoc}
+ * @param array $form
+ * @param \Drupal\Core\Form\FormStateInterface $form_state
+ *
+ * @return void
  */
 function _silverback_ai_import_form_submit(array $form, FormStateInterface $form_state) {
 

packages/drupal/silverback_ai/modules/silverback_ai_import/src/ContentImportAiService.php

@@ -16,6 +16,7 @@
 use Drupal\silverback_ai\HttpClient\OpenAiHttpClient;
 use GuzzleHttp\Exception\RequestException;
 use Drupal\silverback_ai\AiService;
+use JsonException as JsonExceptionAlias;
 
 /**
  * @todo Add class description.
@@ -58,7 +59,7 @@ public function __construct(
    * @return mixed
    *   The processed chunk after plugin conversion
    *
-   * @throws \JsonException
+   * @throws JsonExceptionAlias
    *   When JSON encoding/decoding fails.
    * @throws \RuntimeException
    *   When no appropriate plugin is found for the chunk.
@@ -100,7 +101,7 @@ public function getAst(FileInterface|string $source, $type =  self::DOCX) {
    * @return mixed
    *   The decoded JSON response containing the AST from the external service, or NULL if the request fails.
    *
-   * @throws \GuzzleHttp\Exception\RequestException
+   * @throws \GuzzleHttp\Exception\RequestException|\GuzzleHttp\Exception\GuzzleException
    *   Thrown when the HTTP request fails, though it is caught and logged within this method.
    *
    * @todo Implement configuration handling for service endpoints or client headers.
@@ -143,7 +144,6 @@ private function getAstFromFilePath(FileInterface $file) {
    *
    * @throws \GuzzleHttp\Exception\GuzzleException
    *   When the HTTP request fails
-   * @throws \JsonException
    *   When JSON decoding fails
    *
    * @todo Extend support for other file types besides DOCX
@@ -161,12 +161,13 @@ private function getAstFromUrl(string $url) {
         ],
       ]);
       $body = $response->getBody()->getContents();
-      $response = json_decode($body);
+      return json_decode($body);
     } catch (RequestException $e) {
       // Handle any errors.
       $this->loggerFactory->get('silverback_ai_import')->error($e->getMessage());
     }
-    return $response;
+
+    return NULL;
   }
 
   /**
@@ -185,8 +186,6 @@ private function getAstFromUrl(string $url) {
    *
    * @throws \GuzzleHttp\Exception\GuzzleException
    *   When the HTTP request fails
-   * @throws \JsonException
-   *   When JSON decoding fails
    * @throws \RuntimeException
    *   When stream wrapper manager fails to resolve the file path
    *
@@ -216,7 +215,13 @@ private function getAstFromPdfFile(FileInterface $file) {
   }
 
   /**
-   * {Helper method}
+   * Helper method.
+   *
+   * @param string $ast
+   * @param string $schema
+   *
+   * @return array
+   * @throws \Exception
    */
   public function extractData(string $ast, string $schema) {
     $model = $this->configFactory->get('silverback_ai_import.settings')->get('ai_model') ?: self::DEFAULT_AI_MODEL;
@@ -252,7 +257,15 @@ public function extractData(string $ast, string $schema) {
   }
 
   /**
-   * {Helper method}
+   * Send the AI request.
+   *
+   * @param string $ast
+   * @param string $type
+   * @param string $template
+   * @param string $schema
+   *
+   * @return array
+   * @throws \Exception
    */
   public function sendOpenAiRequest(string $ast, string $type, string $template, string $schema) {
 
@@ -302,7 +315,12 @@ public function sendOpenAiRequest(string $ast, string $type, string $template, s
   }
 
   /**
-   * {Helper method}
+   * Extract data from markdown using AI.
+   *
+   * @param string $markdown
+   *
+   * @return array
+   * @throws \Exception
    */
   public function extractBaseDataFromMarkdown(string $markdown) {
 
@@ -344,14 +362,15 @@ public function extractBaseDataFromMarkdown(string $markdown) {
    * that matches the provided chunk. The first matching plugin instance
    * will be selected and returned.
    *
-   * @todo Order the plugin definitions by weight before attempting to find a match.
-   *
    * @param array $chunk
    *   The input data that will be used to match against plugin definitions.
    *
    * @return object
    *   The plugin instance that matches the provided chunk or the default
    *   plugin if no matches are found.
+   * @throws \Drupal\Component\Plugin\Exception\PluginException
+   * @todo Order the plugin definitions by weight before attempting to find a match.
+   *
    */
   public function getPlugin(array $chunk) {
     $default_plugin = $this->pluginManager->createInstance('ai_default');
@@ -385,7 +404,7 @@ public function getPlugin(array $chunk) {
    *  - parent: Reference to the parent node's ID
    *  - Additional properties specific to each node type
    */
-  public function flattenAst($ast, $parent = NULL) {
+  public function flattenAst($ast, int $parent = NULL) {
 
     $ast = json_decode(json_encode($ast), TRUE);
     static $flatNodes = [];
@@ -449,9 +468,8 @@ public function flattenAst($ast, $parent = NULL) {
    *                     ].
    * @param int $depth
    *   Current depth in the recursive traversal (default: 0)
-   *
-   * @return void
-   *
+Ω   *
+   * @throws \JsonException
    * @see processChunk() Method used to process Image type items
    */
   public function iterateArray(array &$data, int $depth = 0): void {
@@ -571,8 +589,6 @@ public function extractPageDataFromUrl($url) {
    *   When there's an error saving the node entity
    * @throws \RuntimeException
    *   When the content.md file cannot be read
-   * @throws \JsonException
-   *   When JSON decoding fails
    *
    * @see \Drupal\node\Entity\Node::create()
    */
@@ -607,6 +623,7 @@ public function createEntityFromDocxAst($ast) {
    *   or NULL if required data is missing
    *
    * @throws \Drupal\Core\Entity\EntityStorageException
+   * @throws \Exception
    *   When there's an error saving the node entity
    *
    * @see \Drupal\node\Entity\Node::create()
@@ -665,7 +682,9 @@ public function createFileEntityFromDropzoneData($file_data) {
   }
 
   /**
-   * @todo Add comment
+   * Get all post import plugins.
+   *
+   * @return array
    */
   public function getPostImportPlugins() {
     $definitions = $this->pluginManagerPost->getDefinitions();
@@ -677,7 +696,13 @@ public function getPostImportPlugins() {
   }
 
   /**
-   * @todo Add comment
+   * Post import process for plugin.
+   *
+   * @param $plugin_id
+   * @param $chunks
+   *
+   * @return mixed
+   * @throws \Drupal\Component\Plugin\Exception\PluginException
    */
   public function postProcessChunks($plugin_id, $chunks,) {
     $plugin = $this->pluginManagerPost->createInstance($plugin_id);

packages/drupal/silverback_ai/modules/silverback_ai_import/src/ContentImportLoggerService.php

@@ -41,7 +41,11 @@ public function __construct(
   }
 
   /**
-   * {@inheritdoc}
+   * @param $ast
+   * @param \Drupal\Core\Entity\EntityInterface $entity
+   * @param string $source
+   *
+   * @return void
    */
   public function createEntry($ast, EntityInterface $entity, string $source): void {
 
@@ -119,7 +123,7 @@ public function getEntries() {
    *   'model', and 'module'.
    *
    * @return array
-   *   A renderable array with the following elements:
+   *   Array with the following elements:
    *   - 'timestamp': The formatted timestamp of when the entry was created.
    *   - 'username': The display name of the user associated with the entry.
    *   - 'entity_id': The capitalized entity bundle string or empty string if

packages/drupal/silverback_ai/src/AiService.php

@@ -78,7 +78,10 @@ public function request(string $prompt, string $model = self::DEFAULT_AI_MODEL,
   }
 
   /**
-   * ...
+   * List OpenAI available models.
+   *
+   * @return array
+   * @throws \GuzzleHttp\Exception\GuzzleException
    */
   public function listModels() {
     try {

packages/drupal/silverback_ai/src/TokenUsage.php

@@ -87,6 +87,8 @@ public function createUsageEntry(array $context): void {
    *
    * @return array
    *   An array of processed database records.
+   * @throws \Drupal\Component\Plugin\Exception\InvalidPluginDefinitionException
+   * @throws \Drupal\Component\Plugin\Exception\PluginNotFoundException
    */
   public function getEntries() {
     $query = $this->connection->select('silverback_ai_usage', 's')