docs: Rewrite documentation to be clearer (#54)

Rewrite documentation to be a little clearer when describing the features the package offers. In addition, update links from -00 to -05 (the latest Internet draft)

#49

README.md

@@ -12,10 +12,10 @@
 
 # Express Security Txt
 
-Express middleware that implements a security.txt path and policy
+Express middleware that implements a security.txt path and policy. Allows the repeating of a directive, as well as the insertion of comments.
 
 References:
-* [security.txt rfc](https://www.ietf.org/id/draft-foudil-securitytxt-00.txt)
+* [security.txt RFC](https://www.ietf.org/id/draft-foudil-securitytxt-05.txt)
 * [security.txt project on github](https://github.com/securitytxt/security-txt)
 
 ## Installation
@@ -26,96 +26,84 @@ yarn add express-security-txt
 
 ## Usage
 
-Define an `options` object with the proper fields that make up a valid
-[security.txt](https://www.ietf.org/id/draft-foudil-securitytxt-00.txt) policy,
-and use it as a middleware for an express app.
+Define an options object with the keys that make up a valid [security.txt](https://www.ietf.org/id/draft-foudil-securitytxt-05.txt) file. All the keys are in camelCase.
 
-```js
+```javascript
 const securityTxt = require('express-security-txt')
 
 const options = {
-  contact: 'mailto:[email protected]',
-  encryption: 'https://www.mykey.com/pgp-key.txt',
-  acknowledgement: 'thank you'
+  contact: 'https://example.com/security/',
+  preferredLanguages: 'en'
 }
 
 app.use(securityTxt.setup(options))
 ```
-### Chaining
 
-Where allowed, you can provide multiple values for a single directive by passing an array.
+### Passing multiple values
 
-```js
-const securityTxt = require('express-security-txt')
+Some directives allow you to specify multiple values. This package allows you to do this by passing an array:
 
+```javascript
 const options = {
-  contact: [
-    'https://firstMethodOfContact.example.com',
-    'https://secondMethodOfContact.example.com'
-  ]
+  contact: ['mailto:[email protected]', 'https://example.com/security/']
 }
-
-app.use(securityTxt.setup(options))
 ```
 
-### Comments
+### Adding comments
 
-To add a comment at the beggining or end of the security.txt file, one may use the keys `_prefixComment` and `_postfixComment` respectively. If one wishes to place a comment immediately before a field, one may use an object which specifies the value of the field and the comment which must come before it.
+Comments can be included in the generated file. The `#` at the beggining of each line of a comment is automatically inserted by the package.
 
-```js
-const securityTxt = require('express-security-txt')
+Comments at the start and end of a file can be added by using the `_prefixComment` and `_postfixComment` keys, like so:
 
+```javascript
 const options = {
-  _prefixComment: 'This comment goes at the very beggining of the file',
-  contact: {
-    comment: 'This comment goes directly before the Contact: directive',
-    value: 'mailto:[email protected]'
-  },
-  encryption: [
-    'https://example.com/encryption',
-    {
-      comment: 'Comments can appear in the middle of an array of values',
-      value: 'https://example.com/alternativeEncryption'
-    }
-  ],
-  _postfixComment: 'This comment goes at the very end of the file'
+  _prefixComment: 'This comment will appear at the beggining of the security.txt file',
+  contact: 'mailto:[email protected]',
+  _postfixComment: 'This comment will appear at the end of the security.txt file'
 }
-
-app.use(securityTxt.setup(options))
 ```
 
-Would generate the file
+NOTE: You may include the newline character (`\n`), and the package will automatically insert the `#` symbol at the beggining of each line.
 
-```txt
-# This comment goes at the very beggining of the file
-# This comment goes directly before the Contact: directive
-Contact: mailto:[email protected]
-Encryption: https://example.com/encryption
-# Comments can appear in the middle of an array of values
-Encryption: https://example.com/alternativeEncryption
-# This comment goes at the very end of the file
-```
+Multiline comments can also be added by specifying an array, where each element is a line of the comment.
+
+<hr>
 
-If your comment spans multiple lines, you can use `\n` to split it. express-security-txt will automatically insert the relevant `#` symbols. Alternatively, one can use an array of lines instead of a string.
+Comments just before a directive can be added by creating an object of the form `{ comment: '...', value: '...' }`, where the value associated with the `value` key is the value of the field; and the `comment` is the comment to appear directly before the field.
 
-For example:
+For example,
 
-```js
+```javascript
 const options = {
-  _prefixComment: ['this is a', 'comment\nwhich', 'spans many lines'],
-  contact: 'mailto:[email protected]'
+  contact: 'https://example.com/security/',
+  acknowledgments: {
+    comment: 'This comment will appear just above the Acknowledgments field',
+    value: 'https://example.com/hall_of_fame'
+  }
 }
 ```
 
-Would generate
+Would become
 
-```txt
-# this is a
-# comment
-# which
-# spans many lines
-Contact: mailto:[email protected]
 ```
+Contact: https://example.com/security/
+# This comment will appear just above the Acknowledgments field
+Acknowledgments: https://example.com/hall_of_fame
+```
+
+<hr>
+
+If a field allows multiple values, you can leave a comment on each one like so:
+
+```javascript
+const options = {
+  contact: [
+    { comment: 'You can rarely reach me by email', value: 'mailto:[email protected]' },
+    { comment: 'Try this online form instead?', value: 'https://example.com/security/' }
+  ]
+}
+```
+
 ## Tests
 
 Project tests:

index.js

@@ -139,7 +139,7 @@ class middleware {
 
   /**
    * validates a security policy object confirms with standards of security.txt
-   * reference: https://www.ietf.org/id/draft-foudil-securitytxt-00.txt
+   * reference: https://www.ietf.org/id/draft-foudil-securitytxt-05.txt
    * @param  {Object} options security policy object properties
    * @return {Boolean}        throws an error or returns true
    */