11/*
22 This source file is part of the Swift.org open source project
33
4- Copyright (c) 2021 Apple Inc. and the Swift project authors
4+ Copyright (c) 2021-2023 Apple Inc. and the Swift project authors
55 Licensed under Apache License v2.0 with Runtime Library Exception
66
77 See https://swift.org/LICENSE.txt for license information
@@ -16,51 +16,89 @@ import SwiftDocC
1616///
1717/// These options are used by the ``Docc/Convert`` subcommand.
1818public struct DocumentationCoverageOptionsArgument : ParsableArguments {
19+ public init ( ) { }
1920
20- static var noCoverage : DocumentationCoverageOptionsArgument {
21- var value = DocumentationCoverageOptionsArgument ( )
22- value. level = . none
23- return value
24- }
25-
26- public init ( ) { }
21+ fileprivate static let noCoverage = DocumentationCoverageOptionsArgument ( )
2722
28- @Flag ( help: """
29- Generates documentation coverage output. (currently Experimental)
30- """ )
23+ // The way the '--experimental-documentation-coverage' flag and the '--coverage-summary-level' option work together
24+ // doesn't match the possible values for `DocumentationCoverageLevel`.
25+
26+ @Flag (
27+ help: ArgumentHelp ( " Generate documentation coverage output. " , discussion: """
28+ Detailed documentation coverage information will be written to 'documentation-coverage.json' in the output directory.
29+ """ )
30+ )
3131 var experimentalDocumentationCoverage : Bool = false
3232
33- /// The desired level of documentation coverage. Options are `none`, `brief`, and `detailed`. The default is `none `
33+ /// The desired level of documentation coverage. Options are `none`, `brief`, and `detailed`. The default is `.brief `
3434 @Option (
35- name: . long, // TODO: `.customLong("level", withSingleDash: true)` doesn't work with `swift run docc …`
36- parsing: . next,
37- help: ArgumentHelp (
38- " Desired level of documentation coverage output. " ) )
35+ name: . customLong( " coverage-summary-level " ) ,
36+ help: ArgumentHelp ( " The level of documentation coverage information to write on standard out. " , discussion: """
37+ The '--coverage-summary-level' level has no impact on the information in the 'documentation-coverage.json' file.
38+ The supported coverage summary levels are 'brief' and 'detailed'.
39+ """ ,
40+ valueName: " symbol-kind " )
41+ )
42+ var summaryLevel : DocumentationCoverageLevel = . brief
43+
44+ @Option ( help: . hidden)
45+ @available ( * , deprecated, renamed: " summaryLevel " )
3946 public var level : DocumentationCoverageLevel = . none
4047
48+ var effectiveSummaryLevel : DocumentationCoverageLevel {
49+ guard experimentalDocumentationCoverage else {
50+ return . none
51+ }
52+ switch summaryLevel {
53+ case . detailed:
54+ return . detailed
55+ case . none, . brief:
56+ return . brief
57+ }
58+ }
59+
4160 @Option (
42- name: . long ,
61+ name: . customLong ( " coverage-symbol-kind-filter " ) ,
4362 parsing: ArrayParsingStrategy . upToNextOption,
44- help: ArgumentHelp (
45- " The kinds of entities to filter generated documentation for. " ,
46- valueName: " kind " ) )
63+ help: ArgumentHelp ( " Filter documentation coverage to only analyze symbols of the specified symbol kinds. " , discussion: """
64+ Specify a list of symbol kind values to filter the documentation coverage to only those types symbols.
65+ The supported symbol kind values are: \
66+ \( DocumentationCoverageOptions . KindFilterOptions. BitFlagRepresentation. allValueStrings. sorted ( ) . joined ( separator: " , " ) )
67+ """ ,
68+ valueName: " symbol-kind " )
69+ )
70+ public var symbolKindFilter : [ DocumentationCoverageOptions . KindFilterOptions . BitFlagRepresentation ] = [ ]
71+
72+ @Option ( parsing: ArrayParsingStrategy . upToNextOption, help: . hidden)
73+ @available ( * , deprecated, renamed: " symbolKindFilter " )
4774 public var kinds : [ DocumentationCoverageOptions . KindFilterOptions . BitFlagRepresentation ] = [ ]
48-
75+
76+ @available ( * , deprecated) // This deprecation silences the access of the deprecated `level` and `kind` options.
77+ public mutating func validate( ) throws {
78+ Docc . Convert. warnAboutDeprecatedOptionIfNeeded ( " level " , message: " Use '--coverage-summary-level' instead. " )
79+ Docc . Convert. warnAboutDeprecatedOptionIfNeeded ( " kinds " , message: " Use '--coverage-symbol-kind-filter' instead. " )
80+
81+ if !ProcessInfo. processInfo. arguments. contains ( " --coverage-summary-level " ) , level != . none {
82+ summaryLevel = level
83+ }
84+ symbolKindFilter. append ( contentsOf: kinds)
85+ }
4986}
5087
5188// SwiftDocCUtilities imports SwiftDocC. SwiftDocC does not link against ArgumentParser (because it isn't about CLI). We conform here because this is the first place that we can. We implement in DocC.
5289extension DocumentationCoverageLevel : ExpressibleByArgument { }
5390extension DocumentationCoverageOptions . KindFilterOptions . BitFlagRepresentation : ExpressibleByArgument { }
5491
5592extension DocumentationCoverageOptions {
56- public init ( from argumentInstance: DocumentationCoverageOptionsArgument ) {
57-
58- if argumentInstance. experimentalDocumentationCoverage {
59- self = DocumentationCoverageOptions (
60- level: argumentInstance. level,
61- kindFilterOptions: DocumentationCoverageOptions . KindFilterOptions ( bitFlags: argumentInstance. kinds) )
62- } else {
93+ public init ( from arguments: DocumentationCoverageOptionsArgument ) {
94+ guard arguments. experimentalDocumentationCoverage else {
6395 self = . noCoverage
96+ return
6497 }
98+
99+ self = DocumentationCoverageOptions (
100+ level: arguments. effectiveSummaryLevel,
101+ kindFilterOptions: . init( bitFlags: arguments. symbolKindFilter)
102+ )
65103 }
66104}
0 commit comments