Merge pull request #211 from jpsim/jp-spm-doc

add way to generate docs for an SPM module

.gitmodules

@@ -10,3 +10,6 @@
 [submodule "Carthage/Checkouts/Result"]
 	path = Carthage/Checkouts/Result
 	url = https://github.com/antitypical/Result.git
+[submodule "Carthage/Checkouts/YamlSwift"]
+	path = Carthage/Checkouts/YamlSwift
+	url = https://github.com/behrang/YamlSwift.git

CHANGELOG.md

@@ -15,6 +15,12 @@
   * `--indent-width (integer)`: number of spaces to indent  
   [JP Simard](https://github.com/jpsim)
 
+* Add `--spm-module [ModuleName]` flag to `doc` to document Swift Package
+  Manager modules. Need to run `swift build` prior to running
+  `sourcekitten doc`. The right Swift toolchain version must also be selected
+  (by setting `TOOLCHAIN_DIR` or similar).  
+  [JP Simard](https://github.com/jpsim)
+
 * Add support `TOOLCHAINS` environment variable to selecting alternative
   toolchains for loading SourceKitService.  
   [Norio Nomura](https://github.com/norio-nomura)

Cartfile

@@ -1 +1,2 @@
 github "drmohundro/SWXMLHash"
+github "behrang/YamlSwift" "master"

Cartfile.resolved

@@ -1,4 +1,5 @@
 github "antitypical/Result" "2.0.0"
 github "drmohundro/SWXMLHash" "2.3.1"
+github "behrang/YamlSwift" "9a3d7b1185fe59f265cda3fb8f06dc4e41080d8a"
 github "jspahrsummers/xcconfigs" "0.9"
 github "Carthage/Commandant" "0.10.0"

Package.swift

@@ -13,6 +13,7 @@ let package = Package(
     .Package(url: "https://github.com/norio-nomura/Clang_C.git", majorVersion: 1),
     .Package(url: "https://github.com/drmohundro/SWXMLHash.git", majorVersion: 2, minor: 3),
     .Package(url: "https://github.com/Carthage/Commandant.git", majorVersion: 0, minor: 9),
+    .Package(url: "https://github.com/behrang/YamlSwift.git", majorVersion: 1, minor: 4),
   ],
   exclude: ["Tests/SourceKittenFramework/Fixtures"]
 )

Source/SourceKittenFramework/Module.swift

@@ -7,6 +7,7 @@
 //
 
 import Foundation
+import Yaml
 
 /// Represents source module to be documented.
 public struct Module {
@@ -33,6 +34,33 @@ public struct Module {
         }
     }
 
+    public init?(spmName: String) {
+        let yamlPath = ".build/debug.yaml"
+        guard let yamlContents = try? String(contentsOfFile: yamlPath),
+            yamlCommands = Yaml.load(yamlContents).value?.dictionary?["commands"]?.dictionary?.values else {
+                return nil
+        }
+        guard let moduleCommand = yamlCommands.filter({ command in
+            command.dictionary?["module-name"]?.string == spmName
+        }).first?.dictionary else {
+            fputs("Could not find SPM module '\(spmName)'. Here are the modules available:\n", stderr)
+            let availableModules = yamlCommands.flatMap({ $0.dictionary?["module-name"]?.string })
+            fputs("\(availableModules.map({ "  - " + $0 }).joinWithSeparator("\n"))\n", stderr)
+            return nil
+        }
+        func stringArray(key: Yaml) -> [String]? {
+            return moduleCommand[key]?.array?.flatMap { $0.string }
+        }
+        guard let imports = stringArray("import-paths"),
+            otherArguments = stringArray("other-args"),
+            sources = stringArray("sources") else {
+                return nil
+        }
+        name = spmName
+        compilerArguments = sources + otherArguments + ["-I"] + imports
+        sourceFiles = sources
+    }
+
     /**
     Failable initializer to create a Module by the arguments necessary pass in to `xcodebuild` to build it.
     Optionally pass in a `moduleName` and `path`.

Source/sourcekitten/Components.plist

@@ -15,6 +15,12 @@
 				<key>RootRelativeBundlePath</key>
 				<string>/usr/local/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/SWXMLHash.framework</string>
 			</dict>
+			<dict>
+				<key>BundleOverwriteAction</key>
+				<string></string>
+				<key>RootRelativeBundlePath</key>
+				<string>/usr/local/Frameworks/SourceKittenFramework.framework/Versions/A/Frameworks/Yaml.framework</string>
+			</dict>
 			<dict>
 				<key>BundleOverwriteAction</key>
 				<string></string>

Source/sourcekitten/DocCommand.swift

@@ -16,19 +16,21 @@ struct DocCommand: CommandType {
     let function = "Print Swift docs as JSON or Objective-C docs as XML"
 
     struct Options: OptionsType {
+        let spmModule: String
         let singleFile: Bool
         let moduleName: String
         let objc: Bool
         let arguments: [String]
 
-        static func create(singleFile: Bool) -> (moduleName: String) -> (objc: Bool) -> (arguments: [String]) -> Options {
-            return { moduleName in { objc in { arguments in
-                self.init(singleFile: singleFile, moduleName: moduleName, objc: objc, arguments: arguments)
-            }}}
+        static func create(spmModule: String) -> (singleFile: Bool) -> (moduleName: String) -> (objc: Bool) -> (arguments: [String]) -> Options {
+            return { singleFile in { moduleName in { objc in { arguments in
+                self.init(spmModule: spmModule, singleFile: singleFile, moduleName: moduleName, objc: objc, arguments: arguments)
+            }}}}
         }
 
         static func evaluate(m: CommandMode) -> Result<Options, CommandantError<SourceKittenError>> {
             return create
+                <*> m <| Option(key: "spm-module", defaultValue: "", usage: "document a Swift Package Manager module")
                 <*> m <| Option(key: "single-file", defaultValue: false, usage: "only document one file")
                 <*> m <| Option(key: "module-name", defaultValue: "",    usage: "name of module to document (can't be used with `--single-file` or `--objc`)")
                 <*> m <| Option(key: "objc",        defaultValue: false, usage: "document Objective-C headers")
@@ -38,7 +40,13 @@ struct DocCommand: CommandType {
 
     func run(options: Options) -> Result<(), SourceKittenError> {
         let args = options.arguments
-        if options.objc {
+        if !options.spmModule.isEmpty {
+            if let docs = Module(spmName: options.spmModule)?.docs {
+                print(docs)
+                return .Success()
+            }
+            return .Failure(.DocFailed)
+        } else if options.objc {
             return runObjC(options, args: args)
         } else if options.singleFile {
             return runSwiftSingleFile(args)

sourcekitten.xcodeproj/project.pbxproj

@@ -27,6 +27,8 @@
 		D0E7B65619E9C76900EDBA4D /* main.swift in Sources */ = {isa = PBXBuildFile; fileRef = D0D1211B19E87861005E4BAA /* main.swift */; };
 		E805A0481B55CBAF00EA654A /* SourceKitTests.swift in Sources */ = {isa = PBXBuildFile; fileRef = E805A0471B55CBAF00EA654A /* SourceKitTests.swift */; };
 		E805A04A1B560FCA00EA654A /* FileTests.swift in Sources */ = {isa = PBXBuildFile; fileRef = E805A0491B560FCA00EA654A /* FileTests.swift */; };
+		E80678051CF2749300AFC816 /* Yaml.framework in Frameworks */ = {isa = PBXBuildFile; fileRef = E80678041CF2749300AFC816 /* Yaml.framework */; };
+		E80678071CF2751400AFC816 /* Yaml.framework in Copy Frameworks */ = {isa = PBXBuildFile; fileRef = E80678041CF2749300AFC816 /* Yaml.framework */; settings = {ATTRIBUTES = (CodeSignOnCopy, RemoveHeadersOnCopy, ); }; };
 		E806D28D1BE0589B00D1BE41 /* SourceLocation.swift in Sources */ = {isa = PBXBuildFile; fileRef = E806D28C1BE0589B00D1BE41 /* SourceLocation.swift */; };
 		E806D28F1BE058B100D1BE41 /* Text.swift in Sources */ = {isa = PBXBuildFile; fileRef = E806D28E1BE058B100D1BE41 /* Text.swift */; };
 		E806D2911BE058C400D1BE41 /* Parameter.swift in Sources */ = {isa = PBXBuildFile; fileRef = E806D2901BE058C400D1BE41 /* Parameter.swift */; };
@@ -103,6 +105,7 @@
 			dstPath = "";
 			dstSubfolderSpec = 10;
 			files = (
+				E80678071CF2751400AFC816 /* Yaml.framework in Copy Frameworks */,
 				E834AE651BED76B30017B386 /* Result.framework in Copy Frameworks */,
 				E834AE641BED76B00017B386 /* Commandant.framework in Copy Frameworks */,
 				E8C0DFCE1AD349E5007EE3D4 /* SWXMLHash.framework in Copy Frameworks */,
@@ -166,6 +169,7 @@
 		E805A0491B560FCA00EA654A /* FileTests.swift */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.swift; path = FileTests.swift; sourceTree = "<group>"; };
 		E80604B21A5D452C0016D959 /* StructureCommand.swift */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.swift; path = StructureCommand.swift; sourceTree = "<group>"; };
 		E80604B41A5D474B0016D959 /* DocCommand.swift */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.swift; path = DocCommand.swift; sourceTree = "<group>"; };
+		E80678041CF2749300AFC816 /* Yaml.framework */ = {isa = PBXFileReference; lastKnownFileType = wrapper.framework; path = Yaml.framework; sourceTree = BUILT_PRODUCTS_DIR; };
 		E806D28C1BE0589B00D1BE41 /* SourceLocation.swift */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.swift; path = SourceLocation.swift; sourceTree = "<group>"; };
 		E806D28E1BE058B100D1BE41 /* Text.swift */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.swift; path = Text.swift; sourceTree = "<group>"; };
 		E806D2901BE058C400D1BE41 /* Parameter.swift */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.swift; path = Parameter.swift; sourceTree = "<group>"; };
@@ -222,6 +226,7 @@
 			isa = PBXFrameworksBuildPhase;
 			buildActionMask = 2147483647;
 			files = (
+				E80678051CF2749300AFC816 /* Yaml.framework in Frameworks */,
 				E8C0DFCD1AD349DB007EE3D4 /* SWXMLHash.framework in Frameworks */,
 			);
 			runOnlyForDeploymentPostprocessing = 0;
@@ -412,6 +417,7 @@
 				E8AB1A2D1A649F2100452012 /* libclang.dylib */,
 				E868473B1A587C6E0043DC65 /* sourcekitd.framework */,
 				E8C0DFCC1AD349DB007EE3D4 /* SWXMLHash.framework */,
+				E80678041CF2749300AFC816 /* Yaml.framework */,
 			);
 			name = "Supporting Files";
 			sourceTree = "<group>";
@@ -730,6 +736,7 @@
 				DYLIB_COMPATIBILITY_VERSION = 1;
 				DYLIB_CURRENT_VERSION = 1;
 				EMBEDDED_CONTENT_CONTAINS_SWIFT = YES;
+				FRAMEWORK_SEARCH_PATHS = "$(inherited)";
 				FRAMEWORK_VERSION = A;
 				INFOPLIST_FILE = Source/SourceKittenFramework/Info.plist;
 				LD_RUNPATH_SEARCH_PATHS = "@loader_path/Frameworks";
@@ -754,6 +761,7 @@
 				DYLIB_COMPATIBILITY_VERSION = 1;
 				DYLIB_CURRENT_VERSION = 1;
 				EMBEDDED_CONTENT_CONTAINS_SWIFT = YES;
+				FRAMEWORK_SEARCH_PATHS = "$(inherited)";
 				FRAMEWORK_VERSION = A;
 				INFOPLIST_FILE = Source/SourceKittenFramework/Info.plist;
 				LD_RUNPATH_SEARCH_PATHS = "@loader_path/Frameworks";
@@ -810,6 +818,7 @@
 				DYLIB_COMPATIBILITY_VERSION = 1;
 				DYLIB_CURRENT_VERSION = 1;
 				EMBEDDED_CONTENT_CONTAINS_SWIFT = YES;
+				FRAMEWORK_SEARCH_PATHS = "$(inherited)";
 				FRAMEWORK_VERSION = A;
 				INFOPLIST_FILE = Source/SourceKittenFramework/Info.plist;
 				LD_RUNPATH_SEARCH_PATHS = "@loader_path/Frameworks";
@@ -855,6 +864,7 @@
 				DYLIB_COMPATIBILITY_VERSION = 1;
 				DYLIB_CURRENT_VERSION = 1;
 				EMBEDDED_CONTENT_CONTAINS_SWIFT = YES;
+				FRAMEWORK_SEARCH_PATHS = "$(inherited)";
 				FRAMEWORK_VERSION = A;
 				INFOPLIST_FILE = Source/SourceKittenFramework/Info.plist;
 				LD_RUNPATH_SEARCH_PATHS = "@loader_path/Frameworks";