Add overview documentation for the SwiftIfConfig library

Author: DougGregor

Sources/SwiftIfConfig/SwiftIfConfig.docc/Info.plist

@@ -0,0 +1,38 @@
+<?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>SwiftIfConfig</string>
+	<key>CFBundleDisplayName</key>
+	<string>SwiftIfConfig</string>
+	<key>CFBundleIdentifier</key>
+	<string>com.apple.swift-if-config</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>
+	<key>CDAppleDefaultAvailability</key>
+	<dict>
+		<key>SwiftIfConfig</key>
+		<array>
+			<dict>
+				<key>name</key>
+				<string>macOS</string>
+				<key>version</key>
+				<string>10.15</string>
+			</dict>
+		</array>
+	</dict>
+</dict>
+</plist>

Sources/SwiftIfConfig/SwiftIfConfig.docc/SwiftIfConfig.md

@@ -0,0 +1,34 @@
+# `SwiftIfConfig`
+
+
+
+A library to evaluate `#if` conditionals within a Swift syntax tree.
+
+## Overview
+
+Swift provides the ability to conditionally compile parts of a source file based on various built-time conditions, including information about the target (operating system, processor architecture, environment), information about the compiler (version, supported attributes and features), and user-supplied conditions specified as part of the build (e.g., `DEBUG`), which we collectively refer to as the *build configuration*. These conditions can occur within a `#if` in the source code, e.g.,
+
+```swift
+func f() {
+#if DEBUG
+  log("called f")
+#endif
+
+#if os(Linux)
+  // use Linux API
+#elseif os(iOS) || os(macOS)
+  // use iOS/macOS API
+#else
+  #error("unsupported platform")
+#endif
+}
+```
+
+The syntax tree and its parser do not reason about the build configuration. Rather, the syntax tree produced by parsing this code will include `IfConfigDeclSyntax` nodes wherever there is a `#if`, and each such node contains the a list of clauses, each with a condition to check (e.g., `os(Linux)`) and a list of syntax nodes that are conditionally part of the program. Therefore, the syntax tree captures all the information needed to process the source file for any build configuration.
+
+The `SwiftIfConfig` library provides utilities to determine which syntax nodes are part of a particular build configuration. Each utility requires that one provide a specific build configuration (i.e., an instance of a type that conforms to the <doc:BuildConfiguration> protocol), and provides a different view on essentially the same information:
+
+* <doc:ActiveSyntaxVisitor> and <doc:ActiveSyntaxAnyVisitor> are visitor types that only visit the syntax nodes that are included ("active") for a given build configuration, implicitly skipping any nodes within inactive `#if` clauses.
+* `SyntaxProtocol.removingInactive(in:)` produces a syntax node that removes all inactive regions (and their corresponding `IfConfigDeclSyntax` nodes) from the given syntax tree, returning a new tree that is free of `#if` conditions.
+* `IfConfigDeclSyntax.activeClause(in:)` determines which of the clauses of an `#if` is active for the given build configuration, returning the active clause.
+* `SyntaxProtocol.isActive(in:)` determines whether the given syntax node is active for the given build configuration.