Skip to content

Commit 27376b8

Browse files
ikhvorostikhvorost
committed
Updated Readme
1 parent d4c26f3 commit 27376b8

File tree

2 files changed

+125
-90
lines changed

2 files changed

+125
-90
lines changed

‎README.md

Lines changed: 125 additions & 85 deletions
Original file line numberDiff line numberDiff line change
@@ -1,140 +1,180 @@
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)
1+
[![Swift: 5.9, 5.8, 5.7](https://img.shields.io/badge/Swift-5.9%20|%205.8%20|%205.7%20-f48041.svg?style=flat)](https://developer.apple.com/swift)
2+
![Platforms: iOS, macOS, tvOS, visionOS, watchOS](https://img.shields.io/badge/Platforms-iOS%20|%20macOS%20|%20tvOS%20|%20visionOS%20|%20watchOS%20-blue.svg?style=flat)
43
[![Swift Package Manager: compatible](https://img.shields.io/badge/Swift%20Package%20Manager-compatible-4BC51D.svg?style=flat)](https://swift.org/package-manager/)
54
[![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)
65
[![codecov](https://codecov.io/gh/ikhvorost/swift-doc-coverage/branch/main/graph/badge.svg?token=5UpPTDzotg)](https://codecov.io/gh/ikhvorost/swift-doc-coverage)
6+
[![Swift Doc Coverage](https://img.shields.io/badge/Swift%20Doc%20Coverage-100%25-f39f37?logo=google-docs&logoColor=white)](https://github.com/ikhvorost/swift-doc-coverage)
77

88
[![Donate](https://www.paypalobjects.com/en_US/i/btn/btn_donate_SM.gif)](https://www.paypal.com/donate/?hosted_button_id=TSPDD3ZAAH24C)
99

10-
<p align="center">
11-
<img src="swift-doc-coverage.png" alt="Swift Doc Coverage: Documentation coverage command-line utility for Swift files">
12-
</p>
13-
1410
# Swift Doc Coverage
1511

16-
`swift-doc-coverage` generates documentation coverage statistics or warnings for Swift files and can be used from the command-line on macOS.
12+
`swift-doc-coverage` tool generates documentation coverage report for Swift files and can be used from the command-line on `macOS`.
1713

1814
## Usage
1915

20-
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.
16+
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.
2117

22-
```terminal
23-
$ swift-doc-coverage --help
18+
```
19+
$ swift-doc-coverage -h
2420
OVERVIEW: Generates documentation coverage statistics for Swift files.
2521
26-
USAGE: swift-doc-coverage [<inputs> ...] [--minimum-access-level <minimum-access-level>] [--report <report>] [--output <output>]
22+
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>]
2723
2824
ARGUMENTS:
29-
<inputs> One or more paths to a directory containing Swift files.
25+
<inputs> One or more paths to directories or Swift files.
3026
3127
OPTIONS:
28+
-s, --skips-hidden-files <skips-hidden-files>
29+
An option to skip hidden files. (default: true)
30+
-i, --ignore-regex <ignore-regex>
31+
Skip source code files with file paths that match the
32+
given regular expression.
3233
-m, --minimum-access-level <minimum-access-level>
33-
The minimum access level of the symbols considered for coverage statistics: open, public, internal, fileprivate, private. (default: public)
34-
-r, --report <report> Report modes: statistics, warnings, json. (default: statistics)
34+
The minimum access level of the symbols considered
35+
for coverage statistics: open, public, internal,
36+
fileprivate, private. (default: public)
37+
-r, --report <report> Report modes: coverage, warnings, json. (default:
38+
coverage)
3539
-o, --output <output> The file path for generated report.
3640
--version Show the version.
3741
-h, --help Show help information.
3842
```
3943

40-
### Statistics report
44+
### Documentation coverage
4145

42-
```terminal
43-
$ swift-doc-coverage ./Rect --report statistics --minimum-access-level internal
44-
1) ./Rect/Rect.swift: 50% [2/4]
46+
To get the documentation coverage report of Swift files in your directory for `public` access level and above (`open`) you can simple run:
47+
48+
```
49+
$ swift-doc-coverage ./Resources
50+
1) /Resources/Rect/Rect.swift: 50% [1/2] (0.013s)
4551
Undocumented:
46-
<Rect.swift:9:5> Rect.size
47-
<Rect.swift:12:5> Rect.center
52+
<Rect.swift:14:3> var Rect.center
4853
49-
2) ./Rect/CompactRect.swift: 0% [0/4]
54+
2) /Resources/Size.swift: 0% [0/1] (0.002s)
5055
Undocumented:
51-
<CompactRect.swift:3:1> CompactRect
52-
<CompactRect.swift:4:5> CompactRect.origin
53-
<CompactRect.swift:5:5> CompactRect.size
54-
<CompactRect.swift:6:5> CompactRect.center
56+
<Size.swift:3:1> struct Size
5557
56-
3) ./Rect/AlternativeRect.swift: 0% [0/4]
58+
3) /Resources/Point.swift: 0% [0/1] (0.002s)
5759
Undocumented:
58-
<AlternativeRect.swift:3:1> AlternativeRect
59-
<AlternativeRect.swift:4:5> AlternativeRect.origin
60-
<AlternativeRect.swift:5:5> AlternativeRect.size
61-
<AlternativeRect.swift:6:5> AlternativeRect.center
60+
<Point.swift:3:1> struct Point
61+
6262
63-
Total: 16% [2/12]
63+
Total: 25% [1/4] (0.023s)
6464
```
6565

6666
Where:
67-
- \<Rect.swift:9:5\> - location in format "filename:line:column"
68-
- Rect.size - declaration name
69-
70-
### JSON report
67+
- `file:///Resources/Rect/Rect.swift` - file path to a found Swift file
68+
- `50%` - documentation coverage in percents
69+
- `[1/2]` - documented declarations count vs all found declarations count
70+
- `(0.013s)` - a processing time
71+
- `<Rect.swift:14:3>` - a declaration location in format `<filename:line:column>`
72+
- `var Rect.center` - a declaration name
7173

72-
It's possible to obtain documentation coverage statistics in JSON format:
73-
74-
```terminal
75-
$ swift-doc-coverage ./Rect.swift -r json -m public -o ./Rect.json
76-
```
77-
Rect.json:
78-
```json
79-
{
80-
"sources" : [
81-
{
82-
"path" : "./Rect.swift",
83-
"totalCount" : 4,
84-
"undocumented" : [
85-
{
86-
"line" : 9,
87-
"name" : "Rect.size",
88-
"column" : 5
89-
},
90-
{
91-
"line" : 12,
92-
"name" : "Rect.center",
93-
"column" : 5
94-
}
95-
]
96-
}
97-
]
98-
}
99-
```
74+
You can also provide an other minimum access levels (`private`, `interval` etc.) to get documentation coverage for more declarations in your code.
10075

76+
### Xcode warnings
10177

102-
### XCode
78+
You can integrate the utility into your Xcode project to generate warnings for undocumented declarations by adding a build phase script:
10379

104-
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`
80+
`Your Target` > `Build Phases` > `Add Run Script Phase`
10581

10682
```terminal
10783
swift-doc-coverage "${SOURCE_ROOT}" --report warnings
10884
```
10985

110-
After running the build command you can see next warnings in XCode:
86+
After running `Product` > `Build` command you can see next warnings in Xcode:
11187

11288
```
113-
⚠️ No documentation for 'logger'.
114-
⚠️ No documentation for 'MyClass'.
115-
⚠️ No documentation for 'MyClass.hello()'.
116-
⚠️ No documentation for 'MyClass.init()'.
117-
...
89+
⚠️ No documentation for 'var Rect.center'.
90+
⚠️ No documentation for 'struct Size'.
91+
⚠️ No documentation for 'struct Point'.
11892
```
11993

120-
> 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.
121-
122-
## Installation
123-
124-
### Manually
94+
### JSON
12595

126-
To install the tool run next single command (using `curl`):
96+
It's possible to obtain all Swift declarations of your code in JSON format:
12797

128-
```terminal
129-
$ bash <(curl -s https://raw.githubusercontent.com/ikhvorost/swift-doc-coverage/main/install.sh)
98+
```
99+
$ swift-doc-coverage ./Rect -r json
100+
[
101+
{
102+
"url" : "file:///Rect/Rect.swift",
103+
"declarations" : [
104+
{
105+
"name" : "struct Rect",
106+
"column" : 1,
107+
"accessLevel" : 0,
108+
"keyword" : "struct",
109+
"comments" : [
110+
{
111+
"isDoc" : true,
112+
"text" : "Doc line"
113+
}
114+
],
115+
"line" : 4
116+
},
117+
{
118+
"column" : 3,
119+
"line" : 5,
120+
"comments" : [
121+
],
122+
"accessLevel" : 3,
123+
"name" : "let Rect.index",
124+
"keyword" : "let"
125+
},
126+
{
127+
"name" : "var Rect.origin",
128+
"line" : 8,
129+
"column" : 3,
130+
"comments" : [
131+
{
132+
"isDoc" : true,
133+
"text" : "Doc block"
134+
}
135+
],
136+
"keyword" : "var",
137+
"accessLevel" : 4
138+
},
139+
{
140+
"accessLevel" : 2,
141+
"line" : 11,
142+
"comments" : [
143+
{
144+
"text" : "Comment line",
145+
"isDoc" : false
146+
}
147+
],
148+
"keyword" : "var",
149+
"column" : 3,
150+
"name" : "var Rect.size"
151+
},
152+
{
153+
"name" : "var Rect.center",
154+
"column" : 3,
155+
"line" : 14,
156+
"keyword" : "var",
157+
"accessLevel" : 1,
158+
"comments" : [
159+
{
160+
"text" : "Comment block",
161+
"isDoc" : false
162+
}
163+
]
164+
}
165+
]
166+
}
167+
]
130168
```
131169

132-
OR:
170+
## Installation
133171

134-
```terminal
135-
$ git clone https://github.com/ikhvorost/swift-doc-coverage.git
136-
$ cd swift-doc-coverage
137-
$ sudo make install
172+
To install the tool just run the following commands in Terminal:
173+
174+
```
175+
git clone https://github.com/ikhvorost/swift-doc-coverage.git
176+
cd swift-doc-coverage
177+
sudo make install
138178
```
139179

140180
## License

‎install.sh

Lines changed: 0 additions & 5 deletions
This file was deleted.

0 commit comments

Comments
 (0)