[ios, osx] Use HTML links in documentation

Replaced Markdown syntax with HTML syntax for hyperlinks in documentation comments. HTML links work both inside Xcode (whether Objective-C or Swift) and on the Web (via jazzy).

Fixes #3961.

Cherry-picked from de0705c7ede7fea5980ed220a1160085630bd89e.

6 files changed, 49 insertions, 45 deletions

diff --git a/platform/darwin/include/MGLAccountManager.h b/platform/darwin/include/MGLAccountManager.h
index 5cf729ef3a..63440046f7 100644
--- a/platform/darwin/include/MGLAccountManager.h
+++ b/platform/darwin/include/MGLAccountManager.h
@@ -13,15 +13,16 @@ NS_ASSUME_NONNULL_BEGIN
 #pragma mark Authorizing Access
 
 /**
- Set the [Mapbox access token](https://www.mapbox.com/help/define-access-token/)
+ Set the
+ <a href="https://www.mapbox.com/help/define-access-token/">Mapbox access token</a>
  to be used by all instances of MGLMapView in the current application.
  
  Mapbox-hosted vector tiles and styles require an API access token, which you
  can obtain from the
- [Mapbox account page](https://www.mapbox.com/studio/account/tokens/). Access
- tokens associate requests to Mapbox’s vector tile and style APIs with your
- Mapbox account. They also deter other developers from using your styles without
- your permission.
+ <a href="https://www.mapbox.com/studio/account/tokens/">Mapbox account page</a>.
+ Access tokens associate requests to Mapbox’s vector tile and style APIs with
+ your Mapbox account. They also deter other developers from using your styles
+ without your permission.
  
  @param accessToken A Mapbox access token. Calling this method with a value of
     `nil` has no effect.
@@ -37,8 +38,8 @@ NS_ASSUME_NONNULL_BEGIN
 
 /**
  Returns the
- [Mapbox access token](https://www.mapbox.com/help/define-access-token/) in use
- by instances of MGLMapView in the current application.
+ <a href="https://www.mapbox.com/help/define-access-token/">Mapbox access token</a>
+ in use by instances of MGLMapView in the current application.
  */
 + (nullable NSString *)accessToken;
 
diff --git a/platform/darwin/include/MGLOfflineStorage.h b/platform/darwin/include/MGLOfflineStorage.h
index 5544663d3e..20cc521f2e 100644
--- a/platform/darwin/include/MGLOfflineStorage.h
+++ b/platform/darwin/include/MGLOfflineStorage.h
@@ -211,9 +211,9 @@ typedef void (^MGLOfflinePackRemovalCompletionHandler)(NSError * _Nullable error
  attempt to download additional tiles until already downloaded tiles are removed
  by calling the `-removePack:withCompletionHandler:` method.
  
- @note The [Mapbox Terms of Service](https://www.mapbox.com/tos/) prohibits
-    changing or bypassing this limit without permission from Mapbox. Contact
-    your Mapbox sales representative to have the limit raised.
+ @note The <a href="https://www.mapbox.com/tos/">Mapbox Terms of Service</a>
+    prohibits changing or bypassing this limit without permission from Mapbox.
+    Contact your Mapbox sales representative to have the limit raised.
  */
 - (void)setMaximumAllowedMapboxTiles:(uint64_t)maximumCount;
 
diff --git a/platform/ios/CHANGELOG.md b/platform/ios/CHANGELOG.md
index 7ef2fc616d..b560535bec 100644
--- a/platform/ios/CHANGELOG.md
+++ b/platform/ios/CHANGELOG.md
@@ -6,6 +6,7 @@ Mapbox welcomes participation and contributions from everyone.  If you’d like
 
 - Fixed a hang that could occur if the host application attempts to set user defaults on a background queue. ([#4745](https://github.com/mapbox/mapbox-gl-native/pull/4745))
 - User location heading updates now resume properly when an app becomes active again. ([#4674](https://github.com/mapbox/mapbox-gl-native/pull/4674))
+- Fixed an issue causing hyperlinks in the documentation to be displayed as raw Markdown syntax when viewed in Xcode’s Quick Help popover or sidebar. ([#4760](https://github.com/mapbox/mapbox-gl-native/pull/4760))
 
 ## 3.2.0
 
diff --git a/platform/ios/include/MGLMapView.h b/platform/ios/include/MGLMapView.h
index 1a17507aeb..bfc1d3c679 100644
--- a/platform/ios/include/MGLMapView.h
+++ b/platform/ios/include/MGLMapView.h
@@ -52,23 +52,24 @@ typedef NS_OPTIONS(NSUInteger, MGLMapDebugMaskOptions) {
  viewpoints, and present information in the form of annotations and overlays.
  
  The map view loads scalable vector tiles that conform to the
- [Mapbox Vector Tile Specification](https://github.com/mapbox/vector-tile-spec).
+ <a href="https://github.com/mapbox/vector-tile-spec">Mapbox Vector Tile Specification</a>.
  It styles them with a style that conforms to the
- [Mapbox GL style specification](https://www.mapbox.com/mapbox-gl-style-spec/).
- Such styles can be designed in [Mapbox Studio](https://www.mapbox.com/studio/)
- and hosted on mapbox.com.
+ <a href="https://www.mapbox.com/mapbox-gl-style-spec/">Mapbox GL style specification</a>.
+ Such styles can be designed in
+ <a href="https://www.mapbox.com/studio/">Mapbox Studio</a> and hosted on
+ mapbox.com.
  
  A collection of Mapbox-hosted styles is available through the `MGLStyle`
  class. These basic styles use
- [Mapbox Streets](https://www.mapbox.com/developers/vector-tiles/mapbox-streets)
- or [Mapbox Satellite](https://www.mapbox.com/satellite/) data sources, but
- you can specify a custom style that makes use of your own data.
+ <a href="https://www.mapbox.com/developers/vector-tiles/mapbox-streets">Mapbox Streets</a>
+ or <a href="https://www.mapbox.com/satellite/">Mapbox Satellite</a> data
+ sources, but you can specify a custom style that makes use of your own data.
  
  Mapbox-hosted vector tiles and styles require an API access token, which you
  can obtain from the
- [Mapbox account page](https://www.mapbox.com/studio/account/tokens/). Access
- tokens associate requests to Mapbox's vector tile and style APIs with your
- Mapbox account. They also deter other developers from using your styles
+ <a href="https://www.mapbox.com/studio/account/tokens/">Mapbox account page</a>.
+ Access tokens associate requests to Mapbox's vector tile and style APIs with
+ your Mapbox account. They also deter other developers from using your styles
  without your permission.
  
  @note You are responsible for getting permission to use the map data and for
@@ -146,7 +147,7 @@ IB_DESIGNABLE
  
  @note The Mapbox terms of service, which governs the use of Mapbox-hosted
     vector tiles and styles,
-    [requires](https://www.mapbox.com/help/mapbox-logo/) most Mapbox
+    <a href="https://www.mapbox.com/help/mapbox-logo/">requires</a> most Mapbox
     customers to display the Mapbox logo. If this applies to you, do not
     hide this view or change its contents.
  */
@@ -158,18 +159,18 @@ IB_DESIGNABLE
  
  @note The Mapbox terms of service, which governs the use of Mapbox-hosted
     vector tiles and styles,
-    [requires](https://www.mapbox.com/help/attribution/) these copyright
-    notices to accompany any map that features Mapbox-designed styles,
+    <a href="https://www.mapbox.com/help/attribution/">requires</a> these
+    copyright notices to accompany any map that features Mapbox-designed styles,
     OpenStreetMap data, or other Mapbox data such as satellite or terrain
     data. If that applies to this map view, do not hide this view or remove
     any notices from it.
 
  @note You are additionally
-    [required](https://www.mapbox.com/help/telemetry-opt-out-for-users/) to
-    provide users with the option to disable anonymous usage and location
+    <a href="https://www.mapbox.com/help/telemetry-opt-out-for-users/">required</a>
+    to provide users with the option to disable anonymous usage and location
     sharing (telemetry). If this view is hidden, you must implement this
     setting elsewhere in your app or via `Settings.bundle`. See our
-    [website](https://www.mapbox.com/ios-sdk/#telemetry_opt_out) for
+    <a href="https://www.mapbox.com/ios-sdk/#telemetry_opt_out">website</a> for
     implementation help.
  */
 @property (nonatomic, readonly) UIButton *attributionButton;
diff --git a/platform/ios/src/MGLCompactCalloutView.h b/platform/ios/src/MGLCompactCalloutView.h
index 5f8edd921f..ebe27c842c 100644
--- a/platform/ios/src/MGLCompactCalloutView.h
+++ b/platform/ios/src/MGLCompactCalloutView.h
@@ -2,7 +2,7 @@
 #import "MGLCalloutView.h"
 
 /**
- A concrete implementation of `MGLCalloutView` based on [SMCalloutView](https://github.com/nfarina/calloutview). This callout view displays the represented annotation’s title, subtitle, and accessory views in a compact, two-line layout.
+ A concrete implementation of `MGLCalloutView` based on <a href="https://github.com/nfarina/calloutview">SMCalloutView</a>. This callout view displays the represented annotation’s title, subtitle, and accessory views in a compact, two-line layout.
  */
 @interface MGLCompactCalloutView : SMCalloutView <MGLCalloutView>
 
diff --git a/platform/osx/include/MGLMapView.h b/platform/osx/include/MGLMapView.h
index ca55ba7cd5..f6ba86fb05 100644
--- a/platform/osx/include/MGLMapView.h
+++ b/platform/osx/include/MGLMapView.h
@@ -37,23 +37,24 @@ typedef NS_OPTIONS(NSUInteger, MGLMapDebugMaskOptions) {
     viewpoints, and present information in the form of annotations and overlays.
     
     The map view loads scalable vector tiles that conform to the
-    [Mapbox Vector Tile Specification](https://github.com/mapbox/vector-tile-spec).
+    <a href="https://github.com/mapbox/vector-tile-spec">Mapbox Vector Tile Specification</a>.
     It styles them with a style that conforms to the
-    [Mapbox GL style specification](https://www.mapbox.com/mapbox-gl-style-spec/).
-    Such styles can be designed in [Mapbox Studio](https://www.mapbox.com/studio/)
-    and hosted on mapbox.com.
+    <a href="https://www.mapbox.com/mapbox-gl-style-spec/">Mapbox GL style specification</a>.
+    Such styles can be designed in
+    <a href="https://www.mapbox.com/studio/">Mapbox Studio</a> and hosted on
+    mapbox.com.
     
     A collection of Mapbox-hosted styles is available through the MGLStyle
     class. These basic styles use
-    [Mapbox Streets](https://www.mapbox.com/developers/vector-tiles/mapbox-streets)
-    or [Mapbox Satellite](https://www.mapbox.com/satellite/) data sources, but
-    you can specify a custom style that makes use of your own data.
+    <a href="https://www.mapbox.com/developers/vector-tiles/mapbox-streets">Mapbox Streets</a>
+    or <a href="https://www.mapbox.com/satellite/">Mapbox Satellite</a> data
+    sources, but you can specify a custom style that makes use of your own data.
     
     Mapbox-hosted vector tiles and styles require an API access token, which you
     can obtain from the
-    [Mapbox account page](https://www.mapbox.com/studio/account/tokens/). Access
-    tokens associate requests to Mapbox’s vector tile and style APIs with your
-    Mapbox account. They also deter other developers from using your styles
+    <a href="https://www.mapbox.com/studio/account/tokens/">Mapbox account page</a>.
+    Access tokens associate requests to Mapbox’s vector tile and style APIs with
+    your Mapbox account. They also deter other developers from using your styles
     without your permission.
     
     @note You are responsible for getting permission to use the map data and for
@@ -128,9 +129,9 @@ IB_DESIGNABLE
     
     @note The Mapbox terms of service, which governs the use of Mapbox-hosted
         vector tiles and styles,
-        [requires](https://www.mapbox.com/help/mapbox-logo/) most Mapbox
-        customers to display the Mapbox logo. If this applies to you, do not
-        hide this view or change its contents. */
+        <a href="https://www.mapbox.com/help/mapbox-logo/">requires</a> most
+        Mapbox customers to display the Mapbox logo. If this applies to you, do
+        not hide this view or change its contents. */
 @property (nonatomic, readonly) NSImageView *logoView;
 
 /** A view showing legally required copyright notices, positioned along the
@@ -138,11 +139,11 @@ IB_DESIGNABLE
     
     @note The Mapbox terms of service, which governs the use of Mapbox-hosted
         vector tiles and styles,
-        [requires](https://www.mapbox.com/help/attribution/) these copyright
-        notices to accompany any map that features Mapbox-designed styles,
-        OpenStreetMap data, or other Mapbox data such as satellite or terrain
-        data. If that applies to this map view, do not hide this view or remove
-        any notices from it. */
+        <a href="https://www.mapbox.com/help/attribution/">requires</a> these
+        copyright notices to accompany any map that features Mapbox-designed
+        styles, OpenStreetMap data, or other Mapbox data such as satellite or
+        terrain data. If that applies to this map view, do not hide this view or
+        remove any notices from it. */
 @property (nonatomic, readonly) NSView *attributionView;
 
 #pragma mark Manipulating the viewpoint