swift-doc-coverage tool generates documentation coverage report for Swift files and can be used from the command-line on macOS.
The utility checks code documentation comments for each declaration (class, struct, enum, protocol, func, typealias etc.) in Swift files from provided path(s) and generates the documentation coverage report, Xcode warnings of json.
$ swift-doc-coverage -h
OVERVIEW: Generates documentation coverage statistics for Swift files.
USAGE: swift-doc-coverage <inputs> ... [--skips-hidden-files <skips-hidden-files>] [--ignore-regex <ignore-regex>] [--minimum-access-level <minimum-access-level>] [--report <report>] [--output <output>]
ARGUMENTS:
<inputs> One or more paths to directories or Swift files.
OPTIONS:
-s, --skips-hidden-files <skips-hidden-files>
An option to skip hidden files. (default: true)
-i, --ignore-regex <ignore-regex>
Skip source code files with file paths that match the
given regular expression.
-m, --minimum-access-level <minimum-access-level>
The minimum access level of the symbols considered
for coverage statistics: open, public, internal,
fileprivate, private. (default: public)
-r, --report <report> Report modes: coverage, warnings, json. (default:
coverage)
-o, --output <output> The file path for generated report.
--version Show the version.
-h, --help Show help information.
To get the documentation coverage report of Swift files in your directory for public access level and above (open) you can simple run:
$ swift-doc-coverage ./Resources
1) /Resources/Rect/Rect.swift: 50% [1/2] (0.013s)
Undocumented:
<Rect.swift:14:3> var Rect.center
2) /Resources/Size.swift: 0% [0/1] (0.002s)
Undocumented:
<Size.swift:3:1> struct Size
3) /Resources/Point.swift: 0% [0/1] (0.002s)
Undocumented:
<Point.swift:3:1> struct Point
Total: 25% [1/4] (0.023s)
Where:
file:///Resources/Rect/Rect.swift- file path to a found Swift file50%- documentation coverage in percents[1/2]- documented declarations count vs all found declarations count(0.013s)- a processing time<Rect.swift:14:3>- a declaration location in format<filename:line:column>var Rect.center- a declaration name
You can also provide an other minimum access levels (private, interval etc.) to get documentation coverage for more declarations in your code.
You can integrate the utility into your Xcode project to generate warnings for undocumented declarations by adding a build phase script:
Your Target > Build Phases > Add Run Script Phase
swift-doc-coverage "${SOURCE_ROOT}" --report warnings
After running Product > Build command you can see next warnings in Xcode:
⚠️ No documentation for 'var Rect.center'.
⚠️ No documentation for 'struct Size'.
⚠️ No documentation for 'struct Point'.
It's possible to obtain all Swift declarations of your code in JSON format:
$ swift-doc-coverage ./Rect -r json
[
{
"url" : "file:///Rect/Rect.swift",
"declarations" : [
{
"name" : "struct Rect",
"column" : 1,
"accessLevel" : 0,
"keyword" : "struct",
"comments" : [
{
"isDoc" : true,
"text" : "Doc line"
}
],
"line" : 4
},
{
"column" : 3,
"line" : 5,
"comments" : [
],
"accessLevel" : 3,
"name" : "let Rect.index",
"keyword" : "let"
},
{
"name" : "var Rect.origin",
"line" : 8,
"column" : 3,
"comments" : [
{
"isDoc" : true,
"text" : "Doc block"
}
],
"keyword" : "var",
"accessLevel" : 4
},
{
"accessLevel" : 2,
"line" : 11,
"comments" : [
{
"text" : "Comment line",
"isDoc" : false
}
],
"keyword" : "var",
"column" : 3,
"name" : "var Rect.size"
},
{
"name" : "var Rect.center",
"column" : 3,
"line" : 14,
"keyword" : "var",
"accessLevel" : 1,
"comments" : [
{
"text" : "Comment block",
"isDoc" : false
}
]
}
]
}
]
To install the tool just run the following commands in Terminal:
git clone https://github.com/ikhvorost/swift-doc-coverage.git
cd swift-doc-coverage
sudo make install
swift-doc-coverage is available under the MIT license. See the LICENSE file for more info.