[Link] Improve docblocks and readme for links

UNRELEASED.md

@@ -35,6 +35,7 @@ Use [the changelog guidelines](https://git.io/polaris-changelog-guidelines) to f
 - Converted `ResourceList`, `ResourcePicker`, and `Select` examples to functional components ([#2133](https://github.com/Shopify/polaris-react/pull/2133))
 - Converted `TextField`, `Toast`, and `TopBar` examples to functional components ([#2135](https://github.com/Shopify/polaris-react/pull/2135))
 - Updated the `withContext` section in the [v3 to v4 migration guide](https://github.com/Shopify/polaris-react/blob/master/documentation/guides/migrating-from-v3-to-v4.md) ([#2124](https://github.com/Shopify/polaris-react/pull/2124))
+- Clarify when to use the `external` prop on the `Link` component ([#2153](https://github.com/Shopify/polaris-react/pull/2153))
 
 ### Development workflow
 

src/components/Link/Link.tsx

@@ -14,9 +14,9 @@ export interface LinkProps {
   id?: string;
   /** The url to link to */
   url?: string;
-  /** The content to display inside link */
+  /** The content to display inside the link */
   children?: React.ReactNode;
-  /** Use for a links that open a different site */
+  /** Makes the link open in a new tab */
   external?: boolean;
   /** Makes the link color the same as the current text color and adds an underline */
   monochrome?: boolean;

src/components/Link/README.md

@@ -107,7 +107,7 @@ Monochrome styles will be applied to links rendered within a `Banner`.
 
 ### External link
 
-Use for text links that point to a different website. They will open in a new browser tab or window.
+Use for text links that should open in a new browser tab (or window, depending on the merchant’s browser settings). Use this only when opening a page in the same tab might disrupt the merchant’s workflow.
 
 ```jsx
 <Link url="https://help.shopify.com/manual" external>
@@ -184,7 +184,7 @@ To provide consistency and clarity:
 
 #### External links
 
-The `external` prop adds an icon and a notification that the link opens a new window. Use the `external` prop to make the link open in a new window (or tab, depending on the merchant’s browser settings). Open a page in a new window or tab only when opening a page in the same tab might disrupt the merchant’s workflow.
+The `external` prop adds an icon and a notification that the link opens a new tab. Use the `external` prop to make the link open in a new tab (or window, depending on the merchant’s browser settings). Open a page in a new tab only when opening a page in the same tab might disrupt the merchant’s workflow.
 
 ### Keyboard support
 

src/utilities/link/types.ts

@@ -1,13 +1,13 @@
 export interface LinkLikeComponentProps
   extends React.HTMLProps<HTMLAnchorElement> {
-  /** A destination to link to */
+  /** The url to link to */
   url: string;
-  /** Forces url to open in a new tab */
+  /**	The content to display inside the link */
+  children?: React.ReactNode;
+  /** Makes the link open in a new tab */
   external?: boolean;
-  /** Tells the browser to download the url instead of opening it. Provides a hint for the downloaded filename if it is a string value. */
+  /** Makes the browser download the url instead of opening it. Provides a hint for the downloaded filename if it is a string value. */
   download?: string | boolean;
-  /**	Content to display inside the link */
-  children?: React.ReactNode;
   [key: string]: any;
 }