Update documentation (#602)

Update some documentation, mark some code samples as being
Swift so that syntax highlighting works properly, and hide some
other infrequently-used symbols by adding internal parameter
name underscores.

Author: natecook1000

Sources/ArgumentParser/Documentation.docc/Extensions/Argument.md

@@ -4,7 +4,7 @@
 
 ### Single Arguments
 
-- ``init(help:completion:)-6mld0``
+- ``init(help:completion:)-6pqzn``
 - ``init(help:completion:)-4p94d``
 - ``init(help:completion:transform:)-3fjtc``
 - ``init(help:completion:transform:)-7yn32``
@@ -21,5 +21,4 @@
 
 ### Infrequently Used APIs
 
-- ``init(from:)``
 - ``wrappedValue``

Sources/ArgumentParser/Documentation.docc/Extensions/CommandConfiguration.md

@@ -24,7 +24,3 @@
 - ``version``
 - ``shouldDisplay``
 
-### Deprecated APIs
-
-- ``init(commandName:abstract:discussion:version:shouldDisplay:subcommands:defaultSubcommand:helpNames:)``
-

Sources/ArgumentParser/Documentation.docc/Extensions/Flag.md

@@ -27,7 +27,6 @@
 
 ### Infrequently Used APIs
 
-- ``init(from:)``
 - ``wrappedValue``
 
 ### Supporting Types

Sources/ArgumentParser/Documentation.docc/Extensions/Option.md

@@ -5,12 +5,12 @@
 ### Single Options
 
 - ``init(name:parsing:help:completion:)-7slrf``
-- ``init(name:parsing:help:completion:)-5k0ug``
+- ``init(name:parsing:help:completion:)-4yske``
 - ``init(name:parsing:help:completion:transform:)-2wf44``
 - ``init(name:parsing:help:completion:transform:)-25g7b``
 - ``init(wrappedValue:name:parsing:help:completion:transform:)-2llve``
 - ``SingleValueParsingStrategy``
-- ``init(wrappedValue:name:parsing:help:completion:)-7xcum``
+- ``init(wrappedValue:name:parsing:help:completion:)-7ilku``
 
 ### Array Options
 
@@ -22,11 +22,4 @@
 
 ### Infrequently Used APIs
 
-- ``init(from:)``
 - ``wrappedValue``
-
-### Deprecated APIs
-
-- ``init(wrappedValue:name:parsing:completion:help:)``
-- ``init(wrappedValue:name:parsing:help:completion:)-4pl7h``
-- ``init(wrappedValue:name:parsing:help:completion:transform:)-6rqji``

Sources/ArgumentParser/Documentation.docc/Extensions/OptionGroup.md

@@ -13,7 +13,6 @@
 ### Infrequently Used APIs
 
 - ``init()``
-- ``init(from:)``
 - ``wrappedValue``
 - ``description``
 

Sources/ArgumentParser/Documentation.docc/Extensions/ParsableArguments.md

@@ -22,7 +22,7 @@
 ### Handling Errors
 
 - ``message(for:)``
-- ``fullMessage(for:)``
+- ``fullMessage(for:columns:)``
 - ``exitCode(for:)``
 
 ### Generating Completion Scripts
@@ -33,4 +33,3 @@
 ### Infrequently Used APIs
 
 - ``init()``
-- ``helpMessage(columns:)``

Sources/ArgumentParser/Parsable Properties/Argument.swift

@@ -21,15 +21,17 @@
 /// argument is required, while `greeting` is optional because it has a default
 /// value.
 ///
-///     @main
-///     struct Greet: ParsableCommand {
-///         @Argument var name: String
-///         @Argument var greeting: String = "Hello"
+/// ```swift
+/// @main
+/// struct Greet: ParsableCommand {
+///     @Argument var name: String
+///     @Argument var greeting: String = "Hello"
 ///
-///         mutating func run() {
-///             print("\(greeting) \(name)!")
-///         }
+///     mutating func run() {
+///         print("\(greeting) \(name)!")
 ///     }
+/// }
+/// ```
 ///
 /// You can call this program with just a name or with a name and a
 /// greeting. When you supply both arguments, the first argument is always
@@ -49,8 +51,8 @@ public struct Argument<Value>:
     self._parsedValue = _parsedValue
   }
 
-  public init(from decoder: Decoder) throws {
-    try self.init(_decoder: decoder)
+  public init(from _decoder: Decoder) throws {
+    try self.init(_decoder: _decoder)
   }
 
   /// This initializer works around a quirk of property wrappers, where the

Sources/ArgumentParser/Parsable Properties/Flag.swift

@@ -18,18 +18,20 @@
 /// For example, the following program declares a flag that lets a user indicate
 /// that seconds should be included when printing the time.
 ///
-///     @main
-///     struct Time: ParsableCommand {
-///         @Flag var includeSeconds = false
+/// ```swift
+/// @main
+/// struct Time: ParsableCommand {
+///     @Flag var includeSeconds = false
 ///
-///         mutating func run() {
-///             if includeSeconds {
-///                 print(Date.now.formatted(.dateTime.hour().minute().second()))
-///             } else {
-///                 print(Date.now.formatted(.dateTime.hour().minute()))
-///             }
+///     mutating func run() {
+///         if includeSeconds {
+///             print(Date.now.formatted(.dateTime.hour().minute().second()))
+///         } else {
+///             print(Date.now.formatted(.dateTime.hour().minute()))
 ///         }
 ///     }
+/// }
+/// ```
 ///
 /// `includeSeconds` has a default value of `false`, but becomes `true` if
 /// `--include-seconds` is provided on the command line.
@@ -74,8 +76,8 @@ public struct Flag<Value>: Decodable, ParsedWrapper {
     self._parsedValue = _parsedValue
   }
 
-  public init(from decoder: Decoder) throws {
-    try self.init(_decoder: decoder)
+  public init(from _decoder: Decoder) throws {
+    try self.init(_decoder: _decoder)
   }
 
   /// This initializer works around a quirk of property wrappers, where the

Sources/ArgumentParser/Parsable Properties/Option.swift

@@ -22,19 +22,21 @@
 ///
 /// For example, the following program defines three options:
 ///
-///     @main
-///     struct Greet: ParsableCommand {
-///         @Option var greeting = "Hello"
-///         @Option var age: Int? = nil
-///         @Option var name: String
+/// ```swift
+/// @main
+/// struct Greet: ParsableCommand {
+///     @Option var greeting = "Hello"
+///     @Option var age: Int? = nil
+///     @Option var name: String
 ///
-///         mutating func run() {
-///             print("\(greeting) \(name)!")
-///             if let age = age {
-///                 print("Congrats on making it to the ripe old age of \(age)!")
-///             }
+///     mutating func run() {
+///         print("\(greeting) \(name)!")
+///         if let age = age {
+///             print("Congrats on making it to the ripe old age of \(age)!")
 ///         }
 ///     }
+/// }
+/// ```
 ///
 /// `greeting` has a default value of `"Hello"`, which can be overridden by
 /// providing a different string as an argument, while `age` defaults to `nil`.
@@ -54,8 +56,8 @@ public struct Option<Value>: Decodable, ParsedWrapper {
     self._parsedValue = _parsedValue
   }
 
-  public init(from decoder: Decoder) throws {
-    try self.init(_decoder: decoder)
+  public init(from _decoder: Decoder) throws {
+    try self.init(_decoder: _decoder)
   }
 
   /// This initializer works around a quirk of property wrappers, where the
@@ -278,14 +280,14 @@ extension Option where Value: ExpressibleByArgument {
     Swap the order of the 'help' and 'completion' arguments.
     """)
   public init(
-    wrappedValue: Value,
+    wrappedValue _wrappedValue: Value,
     name: NameSpecification = .long,
     parsing parsingStrategy: SingleValueParsingStrategy = .next,
     completion: CompletionKind?,
     help: ArgumentHelp?
   ) {
     self.init(
-      wrappedValue: wrappedValue,
+      wrappedValue: _wrappedValue,
       name: name,
       parsing: parsingStrategy,
       help: help,
@@ -441,7 +443,7 @@ extension Option {
     """)
   @_disfavoredOverload
   public init<T>(
-    wrappedValue: Optional<T>,
+    wrappedValue _wrappedValue: Optional<T>,
     name: NameSpecification = .long,
     parsing parsingStrategy: SingleValueParsingStrategy = .next,
     help: ArgumentHelp? = nil,
@@ -454,7 +456,7 @@ extension Option {
         kind: .name(key: key, specification: name),
         help: help,
         parsingStrategy: parsingStrategy.base,
-        initial: wrappedValue,
+        initial: _wrappedValue,
         completion: completion)
 
       return ArgumentSet(arg)
@@ -544,7 +546,7 @@ extension Option {
   @_disfavoredOverload
   @preconcurrency
   public init<T>(
-    wrappedValue: Optional<T>,
+    wrappedValue _wrappedValue: Optional<T>,
     name: NameSpecification = .long,
     parsing parsingStrategy: SingleValueParsingStrategy = .next,
     help: ArgumentHelp? = nil,
@@ -559,7 +561,7 @@ extension Option {
         help: help,
         parsingStrategy: parsingStrategy.base,
         transform: transform,
-        initial: wrappedValue,
+        initial: _wrappedValue,
         completion: completion)
 
       return ArgumentSet(arg)

Sources/ArgumentParser/Parsable Properties/OptionGroup.swift

@@ -14,17 +14,19 @@
 /// Use an option group to include a group of options, flags, or arguments
 /// declared in a parsable type.
 ///
-///     struct GlobalOptions: ParsableArguments {
-///         @Flag(name: .shortAndLong)
-///         var verbose: Bool
+/// ```swift
+/// struct GlobalOptions: ParsableArguments {
+///     @Flag(name: .shortAndLong)
+///     var verbose: Bool
 ///
-///         @Argument var values: [Int]
-///     }
+///     @Argument var values: [Int]
+/// }
 ///
-///     struct Options: ParsableArguments {
-///         @Option var name: String
-///         @OptionGroup var globals: GlobalOptions
-///     }
+/// struct Options: ParsableArguments {
+///     @Option var name: String
+///     @OptionGroup var globals: GlobalOptions
+/// }
+/// ```
 ///
 /// The flag and positional arguments declared as part of `GlobalOptions` are
 /// included when parsing `Options`.
@@ -45,14 +47,14 @@ public struct OptionGroup<Value: ParsableArguments>: Decodable, ParsedWrapper {
     self._visibility = .default
   }
 
-  public init(from decoder: Decoder) throws {
-    if let d = decoder as? SingleValueDecoder,
+  public init(from _decoder: Decoder) throws {
+    if let d = _decoder as? SingleValueDecoder,
       let value = try? d.previousValue(Value.self)
     {
       self.init(_parsedValue: .value(value))
     } else {
-      try self.init(_decoder: decoder)
-      if let d = decoder as? SingleValueDecoder {
+      try self.init(_decoder: _decoder)
+      if let d = _decoder as? SingleValueDecoder {
         d.saveValue(wrappedValue)
       }
     }