Merge pull request #8 from apiaryio/kylef/0002-pavan-feedback

Address feedback on RFC 0002 (Authentication Framework)

Author: kylef

rfcs/0002-authentication.md

@@ -54,8 +54,18 @@ following in an API Blueprint:
 **NOTE**: *The basic scheme is used as an example in this RFC, and is not
 defined within this RFC.*
 
-Under the authentication scheme heading, you may define properties within a
-list item. An authentication scheme may provide a set of properties or defaults.
+Under the authentication scheme heading, you may describe authentication
+schemes as MSON Type Sections. You may attach a description and define
+properties as list items.
+
+An authentication scheme may provide a set of properties with default values.
+
+```apib
+### Passphrase (Basic)
+
+Polls API supports the Basic authentication scheme used with
+pre-existing user accounts.
+```
 
 Inside an authentication scheme, you can define responses that may be given
 when an authentication scheme is used. For example to indicate the response
@@ -66,8 +76,8 @@ authentication is incorrect.
 ### Passphrase (Basic)
 
 + Response 403 (application/json)
-
-        { "error": "The user does not have access." }
+    + Attributes
+        + error: `The user does not have access.`
 ```
 
 ## Authenticated Keyword
@@ -104,8 +114,8 @@ You may also provide failure responses in anonymous authentication schemes.
 ```apib
 + Authenticated (Basic)
     + Response 403 (application/json)
-
-            { "error": "The user does not have access." }
+        + Attributes
+            + error: `The user does not have access.`
 ```
 
 You specify that multiple authentication schemes are supported, using an
@@ -119,13 +129,18 @@ You specify that multiple authentication schemes are supported, using an
     + (Passphrase)
 ```
 
+If you do not need to override properties, then you may use the shorthand equivalence:
+
+```apib
++ Authenticated (enum[Basic, Passphrase])
+```
+
 ### Resource Groups
 
 The authenticated keyword may be used within a resource group to indicate that
-all their children resources, actions and example requests inside the
-resource group support the specified authentication schemes. Any
-specific resource, action, or example requests may overide the inherited
-authentication schemes.
+all child resources, actions and requests inside the resource group support
+the specified authentication schemes. Any specific resource, action, or
+request may override the inherited authentication schemes.
 
 Resource groups may be marked as authenticated using the following:
 
@@ -153,8 +168,8 @@ Resource groups may be marked as authenticated using the following:
 
 ### Resources
 
-Similiary to resource groups, a resource and it's children actions and examples
-can be marked as authenticated by placing an `Authenticated` list item.
+Resources, including all the actions and requests within the resource may be
+marked as authenticated using the  `Authenticated` keyword as follows:
 
 ```apib
 ## Questions Collection [/questions]
@@ -172,7 +187,8 @@ can be marked as authenticated by placing an `Authenticated` list item.
 
 ### Actions
 
-You can mark a specific action as authenticated using the following:
+Actions, including all example requests within the action may be marked as
+authenticated using the `Authenticated` keyword as follows:
 
 ```apib
 ### View list of questions [GET]
@@ -209,4 +225,3 @@ keyword inside the request as a sub-item.
 may return within an anonymous authentication scheme inside a request example.
 This limitation is to avoid defining responses within a request to prevent
 complexity.*
-