diff --git a/Sources/SwiftDocCPluginDocumentation/SwiftDocCPlugin.docc/Generating Documentation for Extended Types.md b/Sources/SwiftDocCPluginDocumentation/SwiftDocCPlugin.docc/Generating Documentation for Extended Types.md new file mode 100644 index 0000000..173e811 --- /dev/null +++ b/Sources/SwiftDocCPluginDocumentation/SwiftDocCPlugin.docc/Generating Documentation for Extended Types.md @@ -0,0 +1,54 @@ +# Generating Documentation for Extended Types + +Generate documentation for the extensions you make to types from other modules. + +## Overview + +By default, the Swift-DocC plugin ignores extensions you make to types that are not from the module you're generating documentation for. + +To include documentation for extended types, add the `--include-extended-types` flag to your invocations: + + $ swift package generate-documentation --include-extended-types + +> Note: Extension support is available when using Swift 5.8 or later and the Swift-DocC plugin 1.2 or later. + +## Understanding What is Included by Default + +Not everything that is declared in an extension is hidden behind the `--include-extended-types` flag. If the extension is declared in the same target as the type it is extending, the extension's contents will be included in the documentation by default. + +```swift +public struct Sloth { } + +extension Sloth { + // This function is included in the + // documentation by default. + public func wake() { /* ... */ } +} + +// `Collection` is from the standard library, +// not the `SlothCreator` library, so this is +// what we call an "extended type". +extension Collection where Element == Sloth { + // This property is not included in + // the documentation by default. + public func wake() { + for sloth in self { + sloth.wake() + } + } +} +``` + +## Finding Extended Types in your Documentation + +Extended Types are part of the documentation archive of the target that declares the extensions. + +![The rendered documentation for SlothCreator/Swift/Collection](extended-type-example) + +Within that documentation archive, Extended Types are grouped by the Extended Module they belong to. You can find the latter on your documentation's landing page in a section called "Extended Modules". In our example from above, we have one Extended Module called "Swift" - the name of the standard library. This page can be referenced like this: ` ``SlothCreator/Swift`` `. + +The Extended Type ` ``SlothCreator/Swift/Collection`` ` is a child of the Extended Module and is listed under "Extended Protocols" on the ` ``SlothCreator/Swift`` ` page. + +> Note: The references above use the full path, including the name of the catalog's target, `SlothCreator`. This should help to understand the symbol's exact location, but usually isn't necessary. + + diff --git a/Sources/SwiftDocCPluginDocumentation/SwiftDocCPlugin.docc/Resources/extended-type-example.png b/Sources/SwiftDocCPluginDocumentation/SwiftDocCPlugin.docc/Resources/extended-type-example.png new file mode 100644 index 0000000..790affe Binary files /dev/null and b/Sources/SwiftDocCPluginDocumentation/SwiftDocCPlugin.docc/Resources/extended-type-example.png differ diff --git a/Sources/SwiftDocCPluginDocumentation/SwiftDocCPlugin.docc/Resources/extended-type-example~dark.png b/Sources/SwiftDocCPluginDocumentation/SwiftDocCPlugin.docc/Resources/extended-type-example~dark.png new file mode 100644 index 0000000..b94b353 Binary files /dev/null and b/Sources/SwiftDocCPluginDocumentation/SwiftDocCPlugin.docc/Resources/extended-type-example~dark.png differ diff --git a/Sources/SwiftDocCPluginDocumentation/SwiftDocCPlugin.docc/SwiftDocCPlugin.md b/Sources/SwiftDocCPluginDocumentation/SwiftDocCPlugin.docc/SwiftDocCPlugin.md index 9531250..689a2d3 100644 --- a/Sources/SwiftDocCPluginDocumentation/SwiftDocCPlugin.docc/SwiftDocCPlugin.md +++ b/Sources/SwiftDocCPluginDocumentation/SwiftDocCPlugin.docc/SwiftDocCPlugin.md @@ -33,6 +33,10 @@ following from the command-line: $ swift package generate-documentation +Use the `--help` flag to get a list of all supported arguments: + + $ swift package plugin generate-documentation --help + The documentation on this site is focused on the Swift-DocC plugin specifically. For more general documentation on how to use Swift-DocC, see the documentation [here](https://www.swift.org/documentation/docc/). @@ -43,6 +47,7 @@ general documentation on how to use Swift-DocC, see the documentation - - +- ### Publishing Documentation