Improve documentation

Author: ossus-lib

README.md

@@ -9,7 +9,6 @@ OAuth2 frameworks for **macOS**, **iOS** and **tvOS** written in Swift 5.0.
 - [⤵️ Installation](#installation)
 - [🛠 Usage](#usage)
 - [🖥 Sample macOS app][sample] (with data loader examples)
-- [📱 Sample iOS app](https://github.com/p2/OAuth2PodApp) (using CocoaPods)
 - [📖 Technical Documentation](https://p2.github.io/OAuth2)
 
 OAuth2 requires Xcode 10.2, the built framework can be used on **OS X 10.11** or **iOS 8** and later.
@@ -25,7 +24,7 @@ Code compatible with brand new Swift versions are to be found on a separate feat
 Usage
 -----
 
-To use OAuth2 in your own code, start with `import OAuth2` (use `p2_OAuth2` if you installed _p2.OAuth2_ via CocoaPods) in your source files.
+To use OAuth2 in your own code, start with `import OAuth2` in your source files.
 
 In OAuth2 there are [**different kinds of _flows_**](https://tools.ietf.org/html/rfc6749#page-2).
 This library supports all of them, make sure you're using the correct one for your use-case and authorization server.
@@ -408,6 +407,7 @@ To customize the _go back_ button when using `OAuth2WebViewController` on iOS 8
 
     oauth2.authConfig.ui.backButton = <# UIBarButtonItem(...) #>
 
+See below for settings about [the keychain](#keychain) and [PKCE](#pkce).
 
 Usage with Alamofire
 --------------------
@@ -457,15 +457,15 @@ dynreg.register(client: oauth2) { params, error in
 PKCE
 ----
 
-PKCE support is controlled by the `useProofKeyForCodeExchange` property, and the "use_pkce" setting.
+PKCE support is controlled by the `useProofKeyForCodeExchange` property, and the `use_pkce` key in the settings dictionary.
 It is disabled by default. When enabled, a new code verifier string is generated for every authorization request. 
 
 
 Keychain
 --------
 
 This framework can transparently use the iOS and macOS keychain.
-It is controlled by the `useKeychain` property, which can be disabled during initialization with the "keychain" setting.
+It is controlled by the `useKeychain` property, which can be disabled during initialization with the `keychain` settings dictionary key.
 Since this is **enabled by default**, if you do _not_ turn it off during initialization, the keychain will be queried for tokens and client credentials related to the authorization URL.
 If you turn it off _after_ initialization, the keychain will be queried for existing tokens, but new tokens will not be written to the keychain.
 
@@ -475,14 +475,25 @@ If you have dynamically registered your client and want to start anew, you can c
 Ideally, access tokens get delivered with an "expires_in" parameter that tells you how long the token is valid.
 If it is missing the framework will still use those tokens if one is found in the keychain and not re-perform the OAuth dance.
 You will need to intercept 401s and re-authorize if an access token has expired but the framework has still pulled it from the keychain.
-This behavior can be turned off by supplying "token_assume_unexpired": false in settings or setting `clientConfig.accessTokenAssumeUnexpired` to false.
+This behavior can be turned off by supplying `token_assume_unexpired: false` in settings or setting `clientConfig.accessTokenAssumeUnexpired` to false.
 
+These are the settings dictionary keys you can use for more control:
+
+- `keychain`: a bool on whether to use keychain or not, true by default
+- `keychain_access_mode`: a string value for keychain kSecAttrAccessible attribute, "kSecAttrAccessibleWhenUnlocked" by default, you can change this to e.g. "kSecAttrAccessibleAfterFirstUnlock" if you need the tokens to be available when the phone is locked.
+- `keychain_access_group`: a string value for keychain kSecAttrAccessGroup attribute, nil by default
+- `keychain_account_for_client_credentials`: the name to use to identify client credentials in the keychain, "clientCredentials" by default
+- `keychain_account_for_tokens`: the name to use to identify the tokens in the keychain, "currentTokens" by default
 
 Installation
 ------------
 
-You can use _git_, _Carthage_ and even _CocoaPods_ to install the framework.
-The preferred way is to use _git_ directly or _Carthage_.
+You can use the _Swift Package Manager_, _git_ or _Carthage_.
+The preferred way is to use the _Swift Package Manager_.
+
+#### Swift Package Manager
+
+In Xcode 11 and newer, choose "File" from the Xcode Menu, then "Swift Packages" » "Add Package Dependency..." and paste the URL of this repo: `https://github.com/p2/OAuth2.git`. Pick a version and Xcode should do the rest.
 
 #### Carthage
 
@@ -514,28 +525,6 @@ These three steps are needed to:
 2. Link the framework into your app
 3. Embed the framework in your app when distributing
 
-#### CocoaPods
-
-CocoaPods was nice back in the days for Obj-C and static libraries, but is overkill in the modern days of Swift and iOS frameworks.
-You can however still use OAuth2 with Cocoapods.
-
-Add a `Podfile` that contains at least the following information to the root of your app project, then do `pod install`.
-If you're unfamiliar with CocoaPods, read [using CocoaPods](http://guides.cocoapods.org/using/using-cocoapods.html).
-
-```ruby
-platform :ios, '8.0'          # or platform :osx, '10.9'
-use_frameworks!
-target `YourApp` do
-  pod 'p2.OAuth2', '~> 4.2'
-end
-```
-
-If you want the bleeding edge, use this command for CocoaPods instead – note the `submodules` flag: without it the library will not compile.
-
-```ruby
-pod 'p2.OAuth2', :git => 'https://github.com/p2/OAuth2', :submodules => true
-```
-
 
 License
 -------

Sources/Base/OAuth2Base.swift

@@ -171,6 +171,7 @@ open class OAuth2Base: OAuth2Securable {
 	- secret_in_body (Bool, false by default, forces the flow to use the request body for the client secret)
 	- parameters ([String: String], custom request parameters to be added during authorization)
 	- token_assume_unexpired (Bool, true by default, whether to use access tokens that do not come with an "expires_in" parameter)
+	- use_pkce (Bool, false by default)
 
 	- verbose (Bool, false by default, applies to client logging)
 	*/

Sources/Flows/OAuth2.swift

@@ -73,6 +73,7 @@ open class OAuth2: OAuth2Base {
 	- secret_in_body (Bool, false by default, forces the flow to use the request body for the client secret)
 	- parameters ([String: String], custom request parameters to be added during authorization)
 	- token_assume_unexpired (Bool, true by default, whether to use access tokens that do not come with an "expires_in" parameter)
+	- use_pkce (Bool, false by default)
 
 	- verbose (bool, false by default, applies to client logging)
 	*/