add API reference documentation for PackagePlugin

Sources/PackagePlugin/ArgumentExtractor.swift

@@ -10,7 +10,12 @@
 //
 //===----------------------------------------------------------------------===//
 
-/// A rudimentary helper for extracting options and flags from a string list representing command line arguments. The idea is to extract all known options and flags, leaving just the positional arguments. This does not handle well the case in which positional arguments (or option argument values) happen to have the same name as an option or a flag. It only handles the long `--<name>` form of options, but it does respect `--` as an indication that all remaining arguments are positional.
+/// A rudimentary helper for extracting options and flags from a string list representing command line arguments.
+///
+/// The idea is to extract all known options and flags, leaving just the positional arguments.
+/// This does not handle well the case in which positional arguments (or option argument values) happen to
+/// have the same name as an option or a flag. It only handles the long `--<name>` form of options,
+/// but it does respect `--` as an indication that all remaining arguments are positional.
 public struct ArgumentExtractor {
     private var args: [String]
     private let literals: [String]

Sources/PackagePlugin/Command.swift

@@ -13,7 +13,9 @@
 import Foundation
 
 /// A command to run during the build, including executable, command lines,
-/// environment variables, initial working directory, etc. All paths should be
+/// environment variables, initial working directory, etc.
+///
+/// All paths should be
 /// based on the ones passed to the plugin in the target build context.
 public enum Command {
     /// Returns a command that runs when any of its output files are needed by
@@ -157,7 +159,7 @@ extension Command {
     ///     was generated as if in its source directory; other files are treated
     ///     as resources as if explicitly listed in `Package.swift` using
     ///     `.process(...)`.
-    @available(*, unavailable, message: "specifying the initial working directory for a command is not yet supported")
+    @available(*, unavailable, message: "specifying the initial working directory for a command is not supported")
     public static func buildCommand(
         displayName: String?,
         executable: Path,
@@ -194,8 +196,6 @@ extension Command {
     ///   - executable: The absolute path to the executable to be invoked.
     ///   - arguments: Command-line arguments to be passed to the executable.
     ///   - environment: Environment variable assignments visible to the executable.
-    ///   - workingDirectory: Optional initial working directory when the executable
-    ///     runs.
     ///   - outputFilesDirectory: A directory into which the command writes its
     ///     output files.  Any files there recognizable by their extension as
     ///     source files (e.g. `.swift`) are compiled into the target for which
@@ -244,7 +244,7 @@ extension Command {
     ///     this command was generated as if in its source directory; other
     ///     files are treated as resources as if explicitly listed in
     ///     `Package.swift` using `.process(...)`.
-    @available(*, unavailable, message: "specifying the initial working directory for a command is not yet supported")
+    @available(*, unavailable, message: "specifying the initial working directory for a command is not supported")
     public static func prebuildCommand(
         displayName: String?,
         executable: Path,

Sources/PackagePlugin/Context.swift

@@ -20,7 +20,9 @@ public struct PluginContext {
     public let package: Package
 
     /// The path of a writable directory into which the plugin or the build
-    /// commands it constructs can write anything it wants. This could include
+    /// commands it constructs can write anything it wants.
+    ///
+    /// This could include
     /// any generated source files that should be processed further, and it
     /// could include any caches used by the build tool or the plugin itself.
     /// The plugin is in complete control of what is written under this di-
@@ -35,7 +37,9 @@ public struct PluginContext {
     public let pluginWorkDirectory: Path
 
     /// The path of a writable directory into which the plugin or the build
-    /// commands it constructs can write anything it wants. This could include
+    /// commands it constructs can write anything it wants.
+    ///
+    /// This could include
     /// any generated source files that should be processed further, and it
     /// could include any caches used by the build tool or the plugin itself.
     /// The plugin is in complete control of what is written under this di-
@@ -50,6 +54,7 @@ public struct PluginContext {
     public let pluginWorkDirectoryURL: URL
 
     /// Looks up and returns the path of a named command line executable tool.
+    ///
     /// The executable must be provided by an executable target or a binary
     /// target on which the package plugin target depends. This function throws
     /// an error if the tool cannot be found. The lookup is case sensitive.
@@ -81,7 +86,9 @@ public struct PluginContext {
         throw PluginContextError.toolNotFound(name: name)
     }
 
-    /// A mapping from tool names to their paths and triples. Not directly available
+    /// A mapping from tool names to their paths and triples.
+    ///
+    /// Not directly available
     /// to the plugin, but used by the `tool(named:)` API.
     let accessibleTools: [String: (path: URL, triples: [String]?)]
 

Sources/PackagePlugin/Diagnostics.swift

@@ -11,7 +11,9 @@
 //===----------------------------------------------------------------------===//
 
 /// Emits errors, warnings, and remarks to be shown as a result of running the
-/// plugin. After emitting one or more errors, the plugin should return a
+/// plugin.
+///
+/// After emitting one or more errors, the plugin should return a
 /// non-zero exit code.
 public struct Diagnostics {
 

Sources/PackagePlugin/Documentation.docc/Documentation.md

@@ -0,0 +1,72 @@
+# ``PackagePlugin``
+
+Create plugins that extend the Swift Package Manager.
+
+<!-- swift package --disable-sandbox preview-documentation --target PackagePlugin -->
+## Overview
+
+Build tool plugins generate source files that as part of a build, or perform other actions at the start of every build.
+Build tool plugins are invoked before a package is built in order to construct command invocations to run as part of the build.
+Command plugins provide actions that users can perform at any time and aren't associated with a build.
+
+Read [Writing a build tool plugin](https://docs.swift.org/swiftpm/documentation/packagemanagerdocs/WritingBuildToolPlugin) to learn how to create build tool plugins, or [Writing a command plugin](https://docs.swift.org/swiftpm/documentation/packagemanagerdocs/WritingCommandPlugin) to learn how to create command plugins.
+
+## Topics
+
+### Implementing Command Plugins
+
+- ``CommandPlugin``
+- ``PluginContext``
+- ``Plugin``
+
+### Extracting Arguments
+
+- ``ArgumentExtractor``
+
+### Implementing Build Plugins
+
+- ``BuildToolPlugin``
+- ``PluginContext``
+- ``Target``
+- ``Command``
+
+### Interacting with Package Manager
+
+- ``PackageManager``
+- ``PackageManagerProxyError``
+
+### Inspecting the Package Representation
+
+- ``Package``
+- ``ToolsVersion``
+- ``PackageOrigin``
+- ``PackageDependency``
+- ``Product``
+- ``ExecutableProduct``
+- ``LibraryProduct``
+
+### Inspecting Package Targets
+
+- ``Target``
+- ``TargetDependency``
+- ``SourceModuleTarget``
+- ``ModuleKind``
+- ``SwiftSourceModuleTarget``
+- ``ClangSourceModuleTarget``
+- ``BinaryArtifactTarget``
+- ``SystemLibraryTarget``
+
+### Inspecting Package Files
+
+- ``FileList``
+- ``File``
+- ``FileType``
+
+- ``Path``
+- ``PathList``
+
+### Plugin Diagnostics and Errors
+
+- ``Diagnostics``
+- ``PluginContextError``
+- ``PluginDeserializationError``

Sources/PackagePlugin/Documentation.docc/Info.plist

@@ -0,0 +1,26 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>CFBundleName</key>
+	<string>PackagePlugin</string>
+	<key>CFBundleDisplayName</key>
+	<string>PackagePlugin</string>
+	<key>CFBundleIdentifier</key>
+	<string>org.swift.swiftpm.packageplugin</string>
+	<key>CFBundleDevelopmentRegion</key>
+	<string>en</string>
+	<key>CFBundleIconFile</key>
+	<string>DocumentationIcon</string>
+	<key>CFBundleIconName</key>
+	<string>DocumentationIcon</string>
+	<key>CFBundlePackageType</key>
+	<string>DOCS</string>
+	<key>CFBundleShortVersionString</key>
+	<string>0.1.0</string>
+	<key>CDDefaultCodeListingLanguage</key>
+	<string>swift</string>
+	<key>CFBundleVersion</key>
+	<string>0.1.0</string>
+</dict>
+</plist>

Sources/PackagePlugin/Errors.swift

@@ -10,8 +10,11 @@
 //
 //===----------------------------------------------------------------------===//
 
+/// Errors thrown while using a plugin.
 public enum PluginContextError: Error {
-    /// Could not find a tool with the given name. This could be either because
+    /// Could not find a tool with the given name.
+    ///
+    /// This could be either because
     /// it doesn't exist, or because the plugin doesn't have a dependency on it.
     case toolNotFound(name: String)
 
@@ -40,6 +43,7 @@ extension PluginContextError: CustomStringConvertible {
     }
 }
 
+/// Errors thrown while loading a plugin.
 public enum PluginDeserializationError: Error {
     /// The input JSON is malformed in some way; the message provides more details.
     case malformedInputJSON(_ message: String)

Sources/PackagePlugin/PackageManagerProxy.swift

@@ -13,7 +13,9 @@
 import Foundation
 
 /// Provides specialized information and services from the Swift Package Manager
-/// or an IDE that supports Swift Packages. Different plugin hosts implement the
+/// or an IDE that supports Swift Packages.
+///
+/// Different plugin hosts implement the
 /// functionality in whatever way is appropriate for them, but should preserve
 /// the same semantics described here.
 public struct PackageManager {
@@ -305,6 +307,7 @@ extension PackageManager {
     }
 }
 
+/// Errors from methods using the package manager.
 public enum PackageManagerProxyError: Error {
     /// Indicates that the functionality isn't implemented in the plugin host.
     case unimplemented(_ message: String)