From a1cd7a3b2ff32bf6a0f6083007f59104a85eb4bf Mon Sep 17 00:00:00 2001
From: ArthurHoaro <arthur@hoa.ro>
Date: Thu, 4 Feb 2021 10:53:23 +0100
Subject: ShaarliParsedown: add PHPDoc/comments

---
 .../formatter/Parsedown/ShaarliParsedown.php       |  5 ++++
 .../formatter/Parsedown/ShaarliParsedownExtra.php  |  5 ++++
 .../formatter/Parsedown/ShaarliParsedownTrait.php  | 35 ++++++++++++++++++++--
 3 files changed, 43 insertions(+), 2 deletions(-)

diff --git a/application/formatter/Parsedown/ShaarliParsedown.php b/application/formatter/Parsedown/ShaarliParsedown.php
index d577bdfa..8eb48fda 100644
--- a/application/formatter/Parsedown/ShaarliParsedown.php
+++ b/application/formatter/Parsedown/ShaarliParsedown.php
@@ -4,6 +4,11 @@ declare(strict_types=1);
 
 namespace Shaarli\Formatter\Parsedown;
 
+/**
+ * Parsedown extension for Shaarli.
+ *
+ * Extension for both Parsedown and ParsedownExtra centralized in ShaarliParsedownTrait.
+ */
 class ShaarliParsedown extends \Parsedown
 {
     use ShaarliParsedownTrait;
diff --git a/application/formatter/Parsedown/ShaarliParsedownExtra.php b/application/formatter/Parsedown/ShaarliParsedownExtra.php
index 92ad26ca..15a35da4 100644
--- a/application/formatter/Parsedown/ShaarliParsedownExtra.php
+++ b/application/formatter/Parsedown/ShaarliParsedownExtra.php
@@ -4,6 +4,11 @@ declare(strict_types=1);
 
 namespace Shaarli\Formatter\Parsedown;
 
+/**
+ * ParsedownExtra extension for Shaarli.
+ *
+ * Extension for both Parsedown and ParsedownExtra centralized in ShaarliParsedownTrait.
+ */
 class ShaarliParsedownExtra extends \ParsedownExtra
 {
     use ShaarliParsedownTrait;
diff --git a/application/formatter/Parsedown/ShaarliParsedownTrait.php b/application/formatter/Parsedown/ShaarliParsedownTrait.php
index e6f4dabb..ed7b1747 100644
--- a/application/formatter/Parsedown/ShaarliParsedownTrait.php
+++ b/application/formatter/Parsedown/ShaarliParsedownTrait.php
@@ -6,24 +6,48 @@ namespace Shaarli\Formatter\Parsedown;
 
 use Shaarli\Formatter\BookmarkDefaultFormatter as Formatter;
 
+/**
+ * Trait used for Parsedown and ParsedownExtra extension.
+ *
+ * Extended:
+ *   - Format links properly in search context
+ */
 trait ShaarliParsedownTrait
 {
+    /**
+     * @inheritDoc
+     */
     protected function inlineLink($excerpt)
     {
         return $this->shaarliFormatLink(parent::inlineLink($excerpt), true);
     }
 
+    /**
+     * @inheritDoc
+     */
     protected function inlineUrl($excerpt)
     {
         return $this->shaarliFormatLink(parent::inlineUrl($excerpt), false);
     }
 
+    /**
+     * Properly format markdown link:
+     *   - remove highlight tags from HREF attribute
+     *   - (optional) add highlight tags to link caption
+     *
+     * @param array|null $link     Parsedown formatted link array.
+     *                             It can be empty.
+     * @param bool       $fullWrap Add highlight tags the whole link caption
+     *
+     * @return array|null
+     */
     protected function shaarliFormatLink(?array $link, bool $fullWrap): ?array
     {
+        // If open and clean search tokens are found in the link, process.
         if (
             is_array($link)
-            && strpos($link['element']['attributes']['href'], Formatter::SEARCH_HIGHLIGHT_OPEN) !== false
-            && strpos($link['element']['attributes']['href'], Formatter::SEARCH_HIGHLIGHT_CLOSE) !== false
+            && strpos($link['element']['attributes']['href'] ?? '', Formatter::SEARCH_HIGHLIGHT_OPEN) !== false
+            && strpos($link['element']['attributes']['href'] ?? '', Formatter::SEARCH_HIGHLIGHT_CLOSE) !== false
         ) {
             $link['element']['attributes']['href'] = $this->shaarliRemoveSearchTokens(
                 $link['element']['attributes']['href']
@@ -40,6 +64,13 @@ trait ShaarliParsedownTrait
         return $link;
     }
 
+    /**
+     * Remove open and close tags from provided string.
+     *
+     * @param string $entry input
+     *
+     * @return string Striped input
+     */
     protected function shaarliRemoveSearchTokens(string $entry): string
     {
         $entry = str_replace(Formatter::SEARCH_HIGHLIGHT_OPEN, '', $entry);
-- 
cgit v1.2.3