README tweaks

Author: mattpolzin

README.md

@@ -348,15 +348,16 @@ struct ExampleLoader: ExternalLoader {
     typealias Message = Void
 
     static func load<T>(_ url: URL) async throws -> (T, [Message]) where T : Decodable {
-        // load data from file, perhaps. we will just mock that up for the test:
+        // load data from file, perhaps. we will just mock that up for the example:
         let data = try await mockData(componentKey(type: T.self, at: url))
 
         // We use the YAML decoder purely for order-stability.
         let decoded = try YAMLDecoder().decode(T.self, from: data)
         let finished: T
         // while unnecessary, a loader may likely want to attatch some extra info
-        // to keep track of where a reference was loaded from. This test makes sure
-        // the following strategy of using vendor extensions works.
+        // to keep track of where a reference was loaded from. This example
+        shows
+        // the strategy of using vendor extensions.
         if var extendable = decoded as? VendorExtendable {
             extendable.vendorExtensions["x-source-url"] = AnyCodable(url)
             finished = extendable as! T
@@ -368,6 +369,7 @@ struct ExampleLoader: ExternalLoader {
 
     static func componentKey<T>(type: T.Type, at url: URL) throws -> OpenAPIKit.OpenAPI.ComponentKey {
         // do anything you want here to determine what key the new component should be stored at.
+        //
         // for the example, we will just transform the URL path into a valid components key:
         let urlString = url.pathComponents
           .joined(separator: "_")
@@ -386,7 +388,7 @@ In addition to looking something up in the [`Components`](https://mattpolzin.git
 
 You use a value's [`dereferenced(in:)`](https://mattpolzin.github.io/OpenAPIKit/documentation/openapikit/locallydereferenceable) method to fully dereference it.
 
-You can even dereference the whole document with the `OpenAPI.Document` `locallyDereferenced()` method. As the name implies, you can only derefence whole documents that are contained within one file (which is another way of saying that all references are "local"). Specifically, all references must be located within the document's Components Object. External dereferencing is done as a separeate step, but you can first dereference externally and then dereference internally if you'd like to perform both.
+You can even dereference the whole document with the `OpenAPI.Document` `locallyDereferenced()` method. As the name implies, you can only derefence whole documents that have previously been externally dereferenced (or documents contained within one file) -- that is, all references are "local". Specifically, all references must be located within the document's Components Object. External dereferencing is done as a separeate step, but you can first dereference externally and then dereference internally if you'd like to perform both.
 
 Unlike what happens when you lookup an individual component using the `lookup()` method on `Components`, dereferencing a whole `OpenAPI.Document` will result in type-level changes that guarantee all references are removed. `OpenAPI.Document`'s `locallyDereferenced()` method returns a `DereferencedDocument` which exposes `DereferencedPathItem`s which have `DereferencedParameter`s and `DereferencedOperation`s and so on.