[ios] Add inline examples in documentation

platform/darwin/src/MGLCircleStyleLayer.h

@@ -59,6 +59,8 @@ typedef NS_ENUM(NSUInteger, MGLCircleTranslateAnchor) {
  otherwise, find it using the `MGLStyle.layers` property. You can also create a
  new circle style layer and add it to the style using a method such as
  `-[MGLStyle addLayer:]`.
+
+ <!--EXAMPLE: MGLCircleStyleLayer-->
  */
 @interface MGLCircleStyleLayer : MGLVectorStyleLayer
 

platform/darwin/src/MGLFillStyleLayer.h

@@ -37,6 +37,8 @@ typedef NS_ENUM(NSUInteger, MGLFillTranslateAnchor) {
  otherwise, find it using the `MGLStyle.layers` property. You can also create a
  new fill style layer and add it to the style using a method such as
  `-[MGLStyle addLayer:]`.
+
+ <!--EXAMPLE: MGLFillStyleLayer-->
  */
 @interface MGLFillStyleLayer : MGLVectorStyleLayer
 

platform/darwin/src/MGLLineStyleLayer.h

@@ -87,6 +87,8 @@ typedef NS_ENUM(NSUInteger, MGLLineTranslateAnchor) {
  otherwise, find it using the `MGLStyle.layers` property. You can also create a
  new line style layer and add it to the style using a method such as
  `-[MGLStyle addLayer:]`.
+
+ <!--EXAMPLE: MGLLineStyleLayer-->
  */
 @interface MGLLineStyleLayer : MGLVectorStyleLayer
 

platform/darwin/src/MGLRasterSource.h

@@ -35,6 +35,9 @@ extern const MGLTileSourceOption MGLTileSourceOptionTileSize;
  `MGLRasterSource` object that you can use to initialize new style layers. You
  can also add and remove sources dynamically using methods such as
  `-[MGLStyle addSource:]` and `-[MGLStyle sourceWithIdentifier:]`.
+
+ <!--EXAMPLE: MGLRasterSource-->
+ ```
  */
 @interface MGLRasterSource : MGLTileSource
 

platform/darwin/src/MGLRasterStyleLayer.h

@@ -23,6 +23,8 @@ NS_ASSUME_NONNULL_BEGIN
  otherwise, find it using the `MGLStyle.layers` property. You can also create a
  new raster style layer and add it to the style using a method such as
  `-[MGLStyle addLayer:]`.
+
+ <!--EXAMPLE: MGLRasterStyleLayer-->
  */
 @interface MGLRasterStyleLayer : MGLForegroundStyleLayer
 

platform/darwin/src/MGLShapeSource.h

@@ -74,6 +74,9 @@ extern const MGLShapeSourceOption MGLShapeSourceOptionSimplificationTolerance;
 
  Any vector style layer initialized with a shape source should have a `nil`
  value in its `sourceLayerIdentifier` property.
+
+ <!--EXAMPLE: MGLShapeSource-->
+ ```
  */
 @interface MGLShapeSource : MGLSource
 

platform/darwin/src/MGLSource.h

@@ -16,7 +16,7 @@ NS_ASSUME_NONNULL_BEGIN
  
  Do not create instances of this class directly, and do not create your own
  subclasses of this class. Instead, create instances of `MGLShapeSource` and the
- concrete subclasses of `MGLTileSource`.
+ concrete subclasses of `MGLTileSource`, `MGLVectorSource` and `MGLRasterSource`.
  */
 @interface MGLSource : NSObject
 

platform/darwin/src/MGLStyleLayer.h.ejs

@@ -67,6 +67,8 @@ typedef NS_ENUM(NSUInteger, MGL<%- camelize(property.name) %>) {
  otherwise, find it using the `MGLStyle.layers` property. You can also create a
  new <%- type %> style layer and add it to the style using a method such as
  `-[MGLStyle addLayer:]`.
+
+ <!--EXAMPLE: MGL<%- camelize(type) %>StyleLayer-->
  */
 <% } -%>
 @interface MGL<%- camelize(type) %>StyleLayer : MGL<%-

platform/darwin/src/MGLSymbolStyleLayer.h

@@ -260,6 +260,8 @@ typedef NS_ENUM(NSUInteger, MGLTextTranslateAnchor) {
  otherwise, find it using the `MGLStyle.layers` property. You can also create a
  new symbol style layer and add it to the style using a method such as
  `-[MGLStyle addLayer:]`.
+
+ <!--EXAMPLE: MGLSymbolStyleLayer-->
  */
 @interface MGLSymbolStyleLayer : MGLVectorStyleLayer
 

platform/darwin/src/MGLVectorSource.h

@@ -24,6 +24,9 @@ NS_ASSUME_NONNULL_BEGIN
  (<var>extent</var>&nbsp;×&nbsp;2)&nbsp;−&nbsp;1, inclusive. Any vector style
  layer initialized with a vector source must have a non-`nil` value in its
  `sourceLayerIdentifier` property.
+
+ <!--EXAMPLE: MGLVectorSource-->
+ ```
  */
 @interface MGLVectorSource : MGLTileSource
 

platform/darwin/src/MGLVectorStyleLayer.h

@@ -128,6 +128,8 @@ NS_ASSUME_NONNULL_BEGIN
  style attributes and also `hyphen-minus` and `tag:subtag`. However, you must use
  `%K` in the format string to represent these variables:
  `@"%K == 'LineString'", @"$type"`.
+
+ <!--EXAMPLE: MGLVectorStyleLayer.predicate-->
  */
 @property (nonatomic, nullable) NSPredicate *predicate;
 

platform/ios/ios.xcodeproj/project.pbxproj

@@ -164,6 +164,7 @@
 		40FDA76B1CCAAA6800442548 /* MBXAnnotationView.m in Sources */ = {isa = PBXBuildFile; fileRef = 40FDA76A1CCAAA6800442548 /* MBXAnnotationView.m */; };
 		554180421D2E97DE00012372 /* OpenGLES.framework in Frameworks */ = {isa = PBXBuildFile; fileRef = 554180411D2E97DE00012372 /* OpenGLES.framework */; };
 		55D8C9961D0F18CE00F42F10 /* libsqlite3.tbd in Frameworks */ = {isa = PBXBuildFile; fileRef = 55D8C9951D0F18CE00F42F10 /* libsqlite3.tbd */; };
+		6407D6701E0085FD00F6A9C3 /* MGLDocumentationExampleTests.swift in Sources */ = {isa = PBXBuildFile; fileRef = 6407D66F1E0085FD00F6A9C3 /* MGLDocumentationExampleTests.swift */; };
 		7E016D7E1D9E86BE00A29A21 /* MGLPolyline+MGLAdditions.h in Headers */ = {isa = PBXBuildFile; fileRef = 7E016D7C1D9E86BE00A29A21 /* MGLPolyline+MGLAdditions.h */; };
 		7E016D7F1D9E86BE00A29A21 /* MGLPolyline+MGLAdditions.h in Headers */ = {isa = PBXBuildFile; fileRef = 7E016D7C1D9E86BE00A29A21 /* MGLPolyline+MGLAdditions.h */; };
 		7E016D801D9E86BE00A29A21 /* MGLPolyline+MGLAdditions.m in Sources */ = {isa = PBXBuildFile; fileRef = 7E016D7D1D9E86BE00A29A21 /* MGLPolyline+MGLAdditions.m */; };
@@ -608,6 +609,7 @@
 		554180411D2E97DE00012372 /* OpenGLES.framework */ = {isa = PBXFileReference; lastKnownFileType = wrapper.framework; name = OpenGLES.framework; path = System/Library/Frameworks/OpenGLES.framework; sourceTree = SDKROOT; };
 		55D8C9941D0F133500F42F10 /* config.xcconfig */ = {isa = PBXFileReference; lastKnownFileType = text.xcconfig; name = config.xcconfig; path = ../../build/ios/config.xcconfig; sourceTree = "<group>"; };
 		55D8C9951D0F18CE00F42F10 /* libsqlite3.tbd */ = {isa = PBXFileReference; lastKnownFileType = "sourcecode.text-based-dylib-definition"; name = libsqlite3.tbd; path = usr/lib/libsqlite3.tbd; sourceTree = SDKROOT; };
+		6407D66F1E0085FD00F6A9C3 /* MGLDocumentationExampleTests.swift */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.swift; path = MGLDocumentationExampleTests.swift; sourceTree = "<group>"; };
 		7E016D7C1D9E86BE00A29A21 /* MGLPolyline+MGLAdditions.h */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.h; path = "MGLPolyline+MGLAdditions.h"; sourceTree = "<group>"; };
 		7E016D7D1D9E86BE00A29A21 /* MGLPolyline+MGLAdditions.m */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.objc; path = "MGLPolyline+MGLAdditions.m"; sourceTree = "<group>"; };
 		7E016D821D9E890300A29A21 /* MGLPolygon+MGLAdditions.h */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.h; path = "MGLPolygon+MGLAdditions.h"; sourceTree = "<group>"; };
@@ -1084,6 +1086,7 @@
 				DA35A2C31CCA9F8300E826B2 /* MGLClockDirectionFormatterTests.m */,
 				DA35A2C41CCA9F8300E826B2 /* MGLCompassDirectionFormatterTests.m */,
 				DA35A2A91CCA058D00E826B2 /* MGLCoordinateFormatterTests.m */,
+				6407D66F1E0085FD00F6A9C3 /* MGLDocumentationExampleTests.swift */,
 				DA0CD58F1CF56F6A00A5F5A5 /* MGLFeatureTests.mm */,
 				DA2E885C1CC0382C00F24E7B /* MGLGeometryTests.mm */,
 				DA2DBBCC1D51E80400D38FF9 /* MGLStyleLayerTests.h */,
@@ -1690,6 +1693,7 @@
 				DA8847CE1CBAF91600AB86E3 /* Frameworks */,
 				DA8847CF1CBAF91600AB86E3 /* Headers */,
 				DA8847D01CBAF91600AB86E3 /* Resources */,
+				64E5BF321E09D729005223F7 /* Add Examples to Documentation */,
 			);
 			buildRules = (
 			);
@@ -1724,6 +1728,7 @@
 				DAA4E4101CBB71D400178DFB /* Frameworks */,
 				DAA4E4111CBB71D400178DFB /* CopyFiles */,
 				DABFB85C1CBE99DE00D62B32 /* Headers */,
+				6421B07A1E09EA4B00AF169B /* Add Examples to Documentation */,
 			);
 			buildRules = (
 			);
@@ -1767,16 +1772,18 @@
 				TargetAttributes = {
 					DA1DC9491CB6C1C2006E619F = {
 						CreatedOnToolsVersion = 7.3;
+						LastSwiftMigration = 0820;
 					};
 					DA25D5B81CCD9EDE00607828 = {
 						CreatedOnToolsVersion = 7.3;
 					};
 					DA2E88501CC036F400F24E7B = {
 						CreatedOnToolsVersion = 7.3;
-						LastSwiftMigration = 0800;
+						LastSwiftMigration = 0820;
 					};
 					DA8847D11CBAF91600AB86E3 = {
 						CreatedOnToolsVersion = 7.3;
+						LastSwiftMigration = 0820;
 					};
 					DA8933D41CCD306400E68420 = {
 						CreatedOnToolsVersion = 7.3;
@@ -1913,6 +1920,37 @@
 		};
 /* End PBXResourcesBuildPhase section */
 
+/* Begin PBXShellScriptBuildPhase section */
+		6421B07A1E09EA4B00AF169B /* Add Examples to Documentation */ = {
+			isa = PBXShellScriptBuildPhase;
+			buildActionMask = 2147483647;
+			files = (
+			);
+			inputPaths = (
+			);
+			name = "Add Examples to Documentation";
+			outputPaths = (
+			);
+			runOnlyForDeploymentPostprocessing = 0;
+			shellPath = /bin/sh;
+			shellScript = "node \"${SRCROOT}/scripts/add-examples-to-docs.js\"";
+		};
+		64E5BF321E09D729005223F7 /* Add Examples to Documentation */ = {
+			isa = PBXShellScriptBuildPhase;
+			buildActionMask = 2147483647;
+			files = (
+			);
+			inputPaths = (
+			);
+			name = "Add Examples to Documentation";
+			outputPaths = (
+			);
+			runOnlyForDeploymentPostprocessing = 0;
+			shellPath = /bin/sh;
+			shellScript = "node \"${SRCROOT}/scripts/add-examples-to-docs.js\"";
+		};
+/* End PBXShellScriptBuildPhase section */
+
 /* Begin PBXSourcesBuildPhase section */
 		DA1DC9461CB6C1C2006E619F /* Sources */ = {
 			isa = PBXSourcesBuildPhase;
@@ -1932,6 +1970,7 @@
 			isa = PBXSourcesBuildPhase;
 			buildActionMask = 2147483647;
 			files = (
+				6407D6701E0085FD00F6A9C3 /* MGLDocumentationExampleTests.swift in Sources */,
 				DA2E88631CC0382C00F24E7B /* MGLOfflineRegionTests.m in Sources */,
 				3599A3E61DF708BC00E77FB2 /* MGLStyleValueTests.m in Sources */,
 				DA2E88651CC0382C00F24E7B /* MGLStyleTests.mm in Sources */,
@@ -2314,6 +2353,7 @@
 				LD_RUNPATH_SEARCH_PATHS = "$(inherited) @executable_path/Frameworks";
 				PRODUCT_BUNDLE_IDENTIFIER = com.mapbox.MapboxGL;
 				PRODUCT_NAME = "Mapbox GL";
+				SWIFT_VERSION = 3.0;
 			};
 			name = Debug;
 		};
@@ -2326,6 +2366,7 @@
 				LD_RUNPATH_SEARCH_PATHS = "$(inherited) @executable_path/Frameworks";
 				PRODUCT_BUNDLE_IDENTIFIER = com.mapbox.MapboxGL;
 				PRODUCT_NAME = "Mapbox GL";
+				SWIFT_VERSION = 3.0;
 			};
 			name = Release;
 		};
@@ -2422,6 +2463,7 @@
 				PRODUCT_BUNDLE_IDENTIFIER = com.mapbox.sdk.ios;
 				PRODUCT_NAME = Mapbox;
 				SKIP_INSTALL = YES;
+				SWIFT_VERSION = 3.0;
 				VERSIONING_SYSTEM = "apple-generic";
 				VERSION_INFO_PREFIX = "";
 			};
@@ -2455,6 +2497,7 @@
 				PRODUCT_BUNDLE_IDENTIFIER = com.mapbox.sdk.ios;
 				PRODUCT_NAME = Mapbox;
 				SKIP_INSTALL = YES;
+				SWIFT_VERSION = 3.0;
 				VERSIONING_SYSTEM = "apple-generic";
 				VERSION_INFO_PREFIX = "";
 			};

platform/ios/jazzy.yml

@@ -11,8 +11,6 @@ head: |
 objc: Yes
 skip_undocumented: Yes
 hide_documentation_coverage: Yes
-umbrella_header: src/Mapbox.h
-framework_root: ../darwin/src
 
 custom_categories:
   - name: Maps

platform/ios/scripts/add-examples-to-docs.js

@@ -0,0 +1,65 @@
+'use strict';
+
+const fs = require('fs');
+
+const examples = fs.readFileSync(`${__dirname}/../test/MGLDocumentationExampleTests.swift`, 'utf8');
+
+// Regex extracts the following block
+// /*---BEGIN EXAMPLE: MGLStyleSource---*/
+// /* Frontmatter to describe the example */
+// let sampleCode: String?
+// /*---END EXAMPLE---*/
+//
+// into the following regex groups:
+// 1 (token): " MGLStyleSource"
+// 2 (frontmatter): "/* Frontmatter to describe the example */"
+// 3 (sample code): "let sampleCode: String?"
+const exampleRegex = /\/\*---BEGIN EXAMPLE:(.*)---\*\/\s*(\/\*+[\s\S]*?\*+\/)?([\s\S]*?)\/\*---END EXAMPLE---\*\//gm;
+
+var path = `${process.env.TARGET_BUILD_DIR}/${process.env.PUBLIC_HEADERS_FOLDER_PATH}`;
+
+console.log("Installing examples...");
+
+var match;
+while ((match = exampleRegex.exec(examples)) !== null) {
+  const token = match[1].trim();
+  const className = token.split('.')[0];
+
+  const frontmatter = (match[2] || '')
+    .replace(/\/\*+/g, '') // Remove block comment /**
+    .replace(/\*+\//g, '') // Remove block comment end */
+    .trim()
+    .replace(/\n {8,9}/g, '\n'); // Remove leading whitespace (8-9 spaces incl block comment)
+
+  const exampleCode = match[3]
+    .trim()
+    .replace(/\n {8}/g, '\n'); // Remove leading whitespace (8 spaces)
+
+  // Generate example text
+  var exampleText = "### Example\n\n";
+  if (frontmatter.length > 0) {
+    exampleText += `${frontmatter}\n\n`;
+  }
+  exampleText += "```swift\n" + exampleCode + "\n```";
+  exampleText = exampleText.replace(/\n/g, '\n ');
+
+  const placeholderRegex = new RegExp(`<!--EXAMPLE: ${token}-->`);
+
+  // check if file exists at path
+  const filename = `${path}/${className}.h`;
+
+  if (fs.existsSync(filename)) {
+    const file = fs.readFileSync(filename, 'utf8');
+    // Check for example placeholder in file & update file if found
+    if (placeholderRegex.test(file)) {
+      console.log("Updating example:", filename);
+      fs.writeFileSync(filename, file.replace(placeholderRegex, exampleText));
+    } else if (file.indexOf(exampleText) === -1) {
+      console.log(`Placeholder "${token}" missing:`, filename);
+    } else {
+      console.log(`Example "${token}" already replaced.`);
+    }
+  } else if (token !== "ExampleToken") {
+    console.log("Error file doesn't exist:", filename);
+  }
+}

platform/ios/scripts/document.sh

@@ -35,11 +35,16 @@ cp platform/ios/screenshot.png "${OUTPUT}"
 DEFAULT_THEME="platform/darwin/docs/theme"
 THEME=${JAZZY_THEME:-$DEFAULT_THEME}
 
+DEFAULT_FRAMEWORK_PATH="build/ios/pkg/dynamic/Mapbox.framework"
+FRAMEWORK_PATH=${FRAMEWORK_PATH:-$DEFAULT_FRAMEWORK_PATH}
+
 jazzy \
     --config platform/ios/jazzy.yml \
     --sdk iphonesimulator \
     --github-file-prefix https://github.com/mapbox/mapbox-gl-native/tree/${BRANCH} \
     --module-version ${SHORT_VERSION} \
+    --framework-root ${FRAMEWORK_PATH} \
+    --umbrella-header "${FRAMEWORK_PATH}/Headers/Mapbox.h" \
     --readme ${README} \
     --documentation="platform/ios/docs/Info.plist Keys.md" \
     --root-url https://www.mapbox.com/ios-sdk/api/${RELEASE_VERSION}/ \