@@ -151,10 +151,10 @@ $ swift run swift-dcov SwiftSemantics/Sources/ | jq ".data.symbols[] | select(.d
151
151
While there are plenty of tools for assessing test coverage for code,
152
152
we weren't able to find anything analogous for documentation coverage.
153
153
To this end,
154
- we've contrived a simple JSON format
154
+ we've contrived a simple JSON format
155
155
[inspired by llvm-cov](https://reviews.llvm.org/D22651#change-xdePaVfBugps).
156
156
157
- If you know of an existing standard
157
+ If you know of an existing standard
158
158
that you think might be better suited for this purpose,
159
159
please reach out by [opening an Issue][open an issue]!
160
160
@@ -183,7 +183,7 @@ you can feed the output of `swift-api-inventory` to conventional diffing tools
183
183
to determine API changes between different releases of a project.
184
184
185
185
For example,
186
- here's an API diff between the first beta and latest release candidate of
186
+ here's an API diff between the first beta and latest release candidate of
187
187
[Alamofire 5](https://forums.swift.org/t/alamofire-5-one-year-in-the-making-now-in-beta/18865) :
188
188
189
189
` ` ` terminal
@@ -245,7 +245,7 @@ digraph Anonymous {
245
245
"URLEncodedFormEncoder" [shape=box,peripheries=2];
246
246
"ServerTrustManager" [shape=box];
247
247
"MultipartFormData" [shape=box];
248
-
248
+
249
249
subgraph cluster_Request {
250
250
"DataRequest" [shape=box];
251
251
"Request" [shape=box];
@@ -267,13 +267,13 @@ for both Swift and Objective-C projects.
267
267
Over time, however,
268
268
the way we write Swift code —
269
269
and indeed the language itself —
270
- has evolved to incorporate patterns and features
271
- that are difficult to understand using
270
+ has evolved to incorporate patterns and features
271
+ that are difficult to understand using
272
272
the same documentation standards that served us well for Objective-C.
273
273
274
274
Whereas in Objective-C,
275
275
you could get a complete view of a type's functionality from its class hierarchy,
276
- Swift code today tends to layer and distribute functionality across
276
+ Swift code today tends to layer and distribute functionality across
277
277
[a network of types][swift number protocols diagram].
278
278
While adopting a
279
279
[protocol-oriented paradigm][protocol-oriented programming]
@@ -285,7 +285,7 @@ is to make Swift documentation more useful
285
285
by surfacing the information you need to understand how an API works
286
286
and presenting it in a way that can be easily searched and accessed.
287
287
We want developers to be empowered to use Swift packages to their full extent,
288
- without being reliant on (often outdated) blog posts or Stack Overflow threads.
288
+ without being reliant on (often outdated) blog posts or Stack Overflow threads.
289
289
We want documentation coverage to become as important as test coverage :
290
290
a valuable metric for code quality,
291
291
and an expected part of first-rate open source projects.
@@ -334,7 +334,7 @@ Because it relies only on a syntactic reading of Swift source code,
334
334
without needing code first to be compiled,
335
335
` swift-doc` is quite fast.
336
336
As a baseline,
337
- compare its performance to Jazzy
337
+ compare its performance to Jazzy
338
338
when generating documentation for [SwiftSemantics][swiftsemantics] :
339
339
340
340
` ` ` terminal
@@ -361,17 +361,19 @@ to [a GitHub wiki generated with `swift-doc`][swift-doc swiftsemantics].
361
361
362
362
## What About [ SwiftDoc.org] [ swiftdoc.org ] ?
363
363
364
- ** tl;dr:**
365
- We're currently working on updating SwiftDoc.org for Swift 5,
366
- and hope to have it released later this week.
364
+ ** tl;dr:**
365
+ SwiftDoc.org is now updated for Swift 5.1,
366
+ but we're still working to migrate over a few missing parts
367
+ (notably, the beloved
368
+ [ type inheritance graphs] ( https://swiftdoc.org/v4.2/protocol/expressiblebyfloatliteral/hierarchy/ ) ).
367
369
368
370
SwiftDoc.org,
369
371
[ originally "Swifter"] ( http://natecook.com/blog/2014/09/introducing-swifter/ ) ,
370
- was created by Nate Cook ([ @natecook1000 ] [ @natecook1000 ] )
372
+ was created by Nate Cook ([ @natecook1000 ] [ @natecook1000 ] )
371
373
in September 2014.
372
374
At the time,
373
375
Swift tooling was still in its infancy,
374
- so Nate actually
376
+ so Nate actually
375
377
[ wrote a parser (from scratch!)] ( https://github.com/SwiftDocOrg/swiftdoc-parser )
376
378
to pull symbols and documentation from the Swift standard library.
377
379
Nate became managing editor of [ NSHipster] [ nshipster ] in 2015,
@@ -383,9 +385,9 @@ After the hand-off,
383
385
we were able to get the site updated for Swift 4.2 without too much trouble.
384
386
But when it came time to regenerate the site for Swift 5,
385
387
we found ourselves deep in [ "dependency hell"] [ dependency hell ]
386
- (something to do with the [ regular expression] [ pcre ] library
388
+ (something to do with the [ regular expression] [ pcre ] library
387
389
that Nate had used for the parser).
388
- After begging and pleading with
390
+ After begging and pleading with
389
391
the spirits possessing our ` node_modules ` directory to no avail,
390
392
we decided to roll up our sleeves and get started on a long-term replacement —
391
393
this time, written in Swift.
0 commit comments