From c5f91c4ae92378a59f4f09be2c68f74d873490e1 Mon Sep 17 00:00:00 2001
From: Guy Sartorelli <guy.sartorelli@silverstripe.com>
Date: Mon, 12 Feb 2024 17:33:56 +1300
Subject: [PATCH] DOC Update PHPDocs

---
 src/Form/AbstractLinkField.php | 11 +++++++----
 src/Models/EmailLink.php       |  3 ---
 src/Models/ExternalLink.php    |  3 ---
 src/Models/FileLink.php        |  3 ---
 src/Models/Link.php            |  5 +++--
 src/Models/PhoneLink.php       |  5 +----
 src/Models/SiteTreeLink.php    |  3 ---
 7 files changed, 11 insertions(+), 22 deletions(-)

diff --git a/src/Form/AbstractLinkField.php b/src/Form/AbstractLinkField.php
index 3de5fa3a..f2547b2d 100644
--- a/src/Form/AbstractLinkField.php
+++ b/src/Form/AbstractLinkField.php
@@ -40,8 +40,11 @@ public function getExcludeLinkTextField(): bool
     }
 
     /**
-     * Set allowed types for LinkField
+     * Set which types of link are allowed for this field.
+     * Types must be FQCN of Link subclasses.
+     *
      * @param string[] $types
+     * @throws InvalidArgumentException if $types is empty or any type in the array is invalid
      */
     public function setAllowedTypes(array $types): static
     {
@@ -51,7 +54,7 @@ public function setAllowedTypes(array $types): static
     }
 
     /**
-     * Get allowed types for LinkField
+     * Get the types of link which are allowed for this field.
      */
     public function getAllowedTypes(): array
     {
@@ -59,9 +62,9 @@ public function getAllowedTypes(): array
     }
 
     /**
-     * The method returns an associational array converted to a JSON string,
+     * The method returns a stringified JSON object
      * of available link types with additional parameters necessary
-     * for full-fledged work on the client side.
+     * for work on the client side.
      * @throws InvalidArgumentException
      */
     public function getTypesProp(): string
diff --git a/src/Models/EmailLink.php b/src/Models/EmailLink.php
index dde0ea0e..55cb7829 100644
--- a/src/Models/EmailLink.php
+++ b/src/Models/EmailLink.php
@@ -20,9 +20,6 @@ class EmailLink extends Link
         'Email' => 'Varchar(255)',
     ];
 
-    /**
-     * Set the priority of this link type in the CMS menu
-     */
     private static int $menu_priority = 30;
 
     private static $icon = 'font-icon-p-mail';
diff --git a/src/Models/ExternalLink.php b/src/Models/ExternalLink.php
index a382981f..7d8103ed 100644
--- a/src/Models/ExternalLink.php
+++ b/src/Models/ExternalLink.php
@@ -20,9 +20,6 @@ class ExternalLink extends Link
         'ExternalUrl' => 'Varchar',
     ];
 
-    /**
-     * Set the priority of this link type in the CMS menu
-     */
     private static int $menu_priority = 20;
 
     private static $icon = 'font-icon-external-link';
diff --git a/src/Models/FileLink.php b/src/Models/FileLink.php
index 9ea944d5..72af7f6e 100644
--- a/src/Models/FileLink.php
+++ b/src/Models/FileLink.php
@@ -21,9 +21,6 @@ class FileLink extends Link
         'File' => File::class,
     ];
 
-    /**
-     * Set the priority of this link type in the CMS menu
-     */
     private static int $menu_priority = 10;
 
     private static $icon = 'font-icon-image';
diff --git a/src/Models/Link.php b/src/Models/Link.php
index e4c06af3..0c7be4f9 100644
--- a/src/Models/Link.php
+++ b/src/Models/Link.php
@@ -18,7 +18,7 @@
 use SilverStripe\Forms\Tip;
 
 /**
- * A Link Data Object. This class should be treated as abstract. You should never directly interact with a plain Link
+ * A Link DataObject. This class should be treated as abstract. You should never directly interact with a plain Link
  * instance
  *
  * Note that links should be added via a has_one or has_many relation, NEVER a many_many relation. This is because
@@ -62,7 +62,8 @@ class Link extends DataObject
     private ?string $linkType = null;
 
     /**
-     * Set the priority of this link type in the CMS menu
+     * Set the priority of this link type in the link picker.
+     * A link with a higher priority value will be displayed lower in the list.
      */
     private static int $menu_priority = 100;
 
diff --git a/src/Models/PhoneLink.php b/src/Models/PhoneLink.php
index 7ce981b6..190553be 100644
--- a/src/Models/PhoneLink.php
+++ b/src/Models/PhoneLink.php
@@ -17,11 +17,8 @@ class PhoneLink extends Link
         'Phone' => 'Varchar(255)',
     ];
 
-    /**
-     * Set the priority of this link type in the CMS menu
-     */
     private static int $menu_priority = 40;
-    
+
     private static $icon = 'font-icon-mobile';
 
     public function getCMSFields(): FieldList
diff --git a/src/Models/SiteTreeLink.php b/src/Models/SiteTreeLink.php
index 7c1c4b4b..c704c935 100644
--- a/src/Models/SiteTreeLink.php
+++ b/src/Models/SiteTreeLink.php
@@ -33,9 +33,6 @@ class SiteTreeLink extends Link
         'Page' => SiteTree::class,
     ];
 
-    /**
-     * Set the priority of this link type in the CMS menu
-     */
     private static int $menu_priority = 0;
 
     private static $icon = 'font-icon-page';