Skip to content

Commit 743a0c6

Browse files
committed
Updated Readme
1 parent a1965ae commit 743a0c6

File tree

1 file changed

+130
-3
lines changed

1 file changed

+130
-3
lines changed

README.md

Lines changed: 130 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,140 @@
1+
2+
[![Swift 5](https://img.shields.io/badge/Swift-5-f48041.svg?style=flat)](https://developer.apple.com/swift)
3+
![Platforms: macOS](https://img.shields.io/badge/Platforms-iOS%20|%20macOS%20|%20tvOS%20|%20watchOS%20-blue.svg?style=flat)
4+
[![Swift Package Manager: compatible](https://img.shields.io/badge/Swift%20Package%20Manager-compatible-4BC51D.svg?style=flat)](https://swift.org/package-manager/)
5+
[![Build](https://github.com/ikhvorost/swift-doc-coverage/actions/workflows/swift.yml/badge.svg?branch=main)](https://github.com/ikhvorost/swift-doc-coverage/actions/workflows/swift.yml)
6+
[![codecov](https://codecov.io/gh/ikhvorost/swift-doc-coverage/branch/main/graph/badge.svg?token=5UpPTDzotg)](https://codecov.io/gh/ikhvorost/swift-doc-coverage)
7+
8+
[![Donate](https://www.paypalobjects.com/en_US/i/btn/btn_donate_SM.gif)](https://www.paypal.com/donate/?hosted_button_id=TSPDD3ZAAH24C)
9+
110
# swift-doc-coverage
211

3-
Generates documentation coverage statistics for Swift files.
12+
`swift-doc-coverage` generates documentation coverage statistics or warnings for Swift files and can be used from the command-line on macOS.
13+
14+
## Usage
15+
16+
The utility checks documentation for each declaration (class, structure, enumeration, protocol, type aliase, function, variable etc.) in swift files from provided path(s) and generate the coverage report. You can also provide a minimum access level (public, interval etc.) to include only needed declarations.
17+
18+
```terminal
19+
$ swift-doc-coverage --help
20+
OVERVIEW: Generates documentation coverage statistics for Swift files.
21+
22+
USAGE: swift-doc-coverage [<inputs> ...] [--minimum-access-level <minimum-access-level>] [--report <report>] [--output <output>]
23+
24+
ARGUMENTS:
25+
<inputs> One or more paths to a directory containing Swift files.
26+
27+
OPTIONS:
28+
-m, --minimum-access-level <minimum-access-level>
29+
The minimum access level of the symbols considered for coverage statistics: open, public, internal, fileprivate, private. (default: public)
30+
-r, --report <report> Report modes: statistics, warnings, json. (default: statistics)
31+
-o, --output <output> The file path for generated report.
32+
--version Show the version.
33+
-h, --help Show help information.
34+
```
35+
36+
### Statistics report
37+
38+
```terminal
39+
$ swift-doc-coverage ./Rect --report statistics --minimum-access-level internal
40+
1) ./Rect/Rect.swift: 50% [2/4]
41+
Undocumented:
42+
<Rect.swift:9:5> Rect.size
43+
<Rect.swift:12:5> Rect.center
44+
45+
2) ./Rect/CompactRect.swift: 0% [0/4]
46+
Undocumented:
47+
<CompactRect.swift:3:1> CompactRect
48+
<CompactRect.swift:4:5> CompactRect.origin
49+
<CompactRect.swift:5:5> CompactRect.size
50+
<CompactRect.swift:6:5> CompactRect.center
51+
52+
3) ./Rect/AlternativeRect.swift: 0% [0/4]
53+
Undocumented:
54+
<AlternativeRect.swift:3:1> AlternativeRect
55+
<AlternativeRect.swift:4:5> AlternativeRect.origin
56+
<AlternativeRect.swift:5:5> AlternativeRect.size
57+
<AlternativeRect.swift:6:5> AlternativeRect.center
58+
59+
Total: 16% [2/12]
60+
```
61+
62+
Where:
63+
- \<Rect.swift:9:5\> - location in format "filename:line:column"
64+
- Rect.size - declaration name
65+
66+
### JSON report
67+
68+
It's possible to obtain documentation coverage statistics in JSON format:
69+
70+
```terminal
71+
$ swift-doc-coverage ./Rect.swift -r json -m public -o ./Rect.json
72+
```
73+
Rect.json:
74+
```json
75+
{
76+
"sources" : [
77+
{
78+
"path" : "./Rect.swift",
79+
"totalCount" : 4,
80+
"undocumented" : [
81+
{
82+
"line" : 9,
83+
"name" : "Rect.size",
84+
"column" : 5
85+
},
86+
{
87+
"line" : 12,
88+
"name" : "Rect.center",
89+
"column" : 5
90+
}
91+
]
92+
}
93+
]
94+
}
95+
```
96+
97+
98+
### XCode
99+
100+
You can intergate the utility in your XCode project to generate warnings for undocumented declarations by adding a build phase script: `Your Target` > `Build Phases` > `Add a new buid phase`
101+
102+
```terminal
103+
swift-doc-coverage "${SOURCE_ROOT}" --report warnings
104+
```
105+
106+
After running the build command you can see next warnings in XCode:
107+
108+
```
109+
⚠️ No documentation for 'logger'.
110+
⚠️ No documentation for 'MyClass'.
111+
⚠️ No documentation for 'MyClass.hello()'.
112+
⚠️ No documentation for 'MyClass.init()'.
113+
...
114+
```
115+
116+
> Swift Package Manager: Package.swift doesn't support adding build phase scripts so you need to run the utility manually for your package's folder or convert the package to XCode project.
4117
5118
## Installation
6119

7120
### Manually
8121

9-
Run `install.sh` script from Github with next command to install manually:
122+
To install the tool run next single command (using `curl`):
123+
124+
```terminal
125+
$ bash <(curl -s https://raw.githubusercontent.com/ikhvorost/swift-doc-coverage/main/install.sh)
126+
```
127+
128+
OR:
10129

11130
```terminal
12-
$ sudo bash <(curl -s https://raw.githubusercontent.com/ikhvorost/swift-doc-coverage/main/install.sh)
131+
$ git clone https://github.com/ikhvorost/swift-doc-coverage.git
132+
$ cd swift-doc-coverage
133+
$ sudo make install
13134
```
135+
136+
## License
137+
138+
`swift-doc-coverage` is available under the MIT license. See the [LICENSE](LICENSE) file for more info.
139+
140+
[![Donate](https://www.paypalobjects.com/en_US/i/btn/btn_donate_SM.gif)](https://www.paypal.com/donate/?hosted_button_id=TSPDD3ZAAH24C)

0 commit comments

Comments
 (0)