[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.

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 aa8fbd866c..81a91395aa 100644
--- a/platform/ios/CHANGELOG.md
+++ b/platform/ios/CHANGELOG.md
@@ -15,6 +15,7 @@ Mapbox welcomes participation and contributions from everyone.  If you’d like
 - Added a `-reloadStyle:` action to MGLMapView to force a reload of the current style. ([#4728](https://github.com/mapbox/mapbox-gl-native/pull/4728))
 - A more specific user agent string is now sent with style and tile requests. ([#4012](https://github.com/mapbox/mapbox-gl-native/pull/4012))
 - Mapbox Telemetry is automatically disabled while the host application is running in the iOS Simulator. ([#4726](https://github.com/mapbox/mapbox-gl-native/pull/4726))
+- 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))
 - Removed unused SVG files from the SDK’s resource bundle. ([#4641](https://github.com/mapbox/mapbox-gl-native/pull/4641))
 - Deprecated `-[MGLMapView emptyMemoryCache]`. ([#4725](https://github.com/mapbox/mapbox-gl-native/pull/4725))
 
diff --git a/platform/ios/include/MGLMapView.h b/platform/ios/include/MGLMapView.h
index 79897f0eb5..8518018fd9 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
@@ -160,7 +161,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.
  */
@@ -172,18 +173,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