Add thorough documentation about relationship operations (#71)

* Mention design principle in README

* WIP: Add docs for relationship authorization

* Add back-to-top links

* Move doc-top anchor

* Add doc about PATCH on resource with has-one relationship

* Add doc about POST new resource with has-one relationship

* Add placeholders for has-many relationship documentation

* Fix typo

* Add doc about POST new has-many relationships

* Add doc about DELETE some has-many relationships

* Talk about dissociation instead of removing

We're not "removing" the records, as we're instead only severing the
relationship in the has-one or has-many association.

* Add doc about PATCH has-many relationships

* Add doc about removing of has-many relationships

* Add doc about PATCH on resource with has-many relationship

* Trim unnecessary trailing whitespace from relationship-authorization docs

* Add doc about POST new resource with has-many relationship

* Differentiate relationship replacing and removing with PATCH on resource

* Add newline to end of README.md

* Link to relationship authorization docs from README

* Add consistency caveat to relationship auth docs

* Link to relationship auth docs from Policies part of README.md

* Fix code examples author association

* Add back-to-top link to end of relationship docs

* Describe TOC in terms of HTTP operations

* Mirror sub-headings with TOC

* Split has-one and has-many example setup

* Split docs to two parts and bump heading levels accordingly

Author: valscion

README.md

@@ -14,17 +14,26 @@ branch. This may contain information that is not relevant to the release you are
   [jr]: https://github.com/cerebris/jsonapi-resources "A resource-focused Rails library for developing JSON API compliant servers."
   [pundit]: https://github.com/elabs/pundit "Minimal authorization through OO design and pure Ruby classes"
 
+The core design principle of `JSONAPI::Authorization` is:
+
+**Prefer being overly restrictive rather than too permissive by accident.**
+
+What follows is that we want to have:
+
+1. Whitelist over blacklist -approach for authorization
+2. Fall back on a more strict authorization
+
 ## Caveats
 
 Make sure to test for authorization in your application, too. We should have coverage of all operations, though. If that isn't the case, please [open an issue][issues].
 
 If you're using custom processors, make sure that they extend `JSONAPI::Authorization::AuthorizingProcessor`, or authorization will not be performed for that resource.
 
-This gem should work out-of-the box for simple cases. The default authorizer might be overly restrictive for [more complex cases][complex-case].
+This gem should work out-of-the box for simple cases. The default authorizer might be overly restrictive for cases where you are touching relationships.
 
-The API is subject to change between minor version bumps until we reach v1.0.0.
+**If you are modifying relationships**, you should read the [relationship authorization documentation](docs/relationship-authorization.md).
 
-  [complex-case]: https://github.com/venuu/jsonapi-authorization/issues/15
+The API is subject to change between minor version bumps until we reach v1.0.0.
 
 ## Installation
 
@@ -97,8 +106,7 @@ To check whether an action is allowed JSONAPI::Authorization calls the respectiv
 (`index?`, `show?`, `create?`, `update?`, `destroy?`).
 
 For relationship operations by default `update?` is being called for all affected resources.
-For a finer grained control you can define `add_to_<relation>?`, `replace_<relation>?`, and `remove_from_<relation>?`
-as the following example shows.
+For a finer grained control you can define methods to authorize relationship changes. For example:
 
 ```ruby
 class ArticlePolicy
@@ -120,9 +128,7 @@ class ArticlePolicy
 end
 ```
 
-Caveat: In case a relationship is modifiable through multiple ways it is your responsibility to ensure consistency.
-For example if you have a many-to-many relationship with users and projects make sure that
-`ProjectPolicy#add_to_users?(users)` and `UserPolicy#add_to_projects?(projects)` match up.
+For thorough documentation about custom policy methods, check out the [relationship authorization docs](docs/relationship-authorization.md).
 
 ## Configuration
 
@@ -182,4 +188,4 @@ Thanks goes to these wonderful people ([emoji key](https://github.com/kentcdodds
 | [<img src="https://avatars3.githubusercontent.com/u/4742306?v=3" width="100px;"/><br /><sub>Greg Fisher</sub>](https://github.com/gnfisher)<br />[💻](https://github.com/Venuu/jsonapi-authorization/commits?author=gnfisher) [⚠️](https://github.com/Venuu/jsonapi-authorization/commits?author=gnfisher) | [<img src="https://avatars3.githubusercontent.com/u/370182?v=3" width="100px;"/><br /><sub>Sam</sub>](http://samlh.com)<br />[💻](https://github.com/Venuu/jsonapi-authorization/commits?author=handlers) [⚠️](https://github.com/Venuu/jsonapi-authorization/commits?author=handlers) | [<img src="https://avatars0.githubusercontent.com/u/2738630?v=3" width="100px;"/><br /><sub>Justas Palumickas</sub>](https://jpalumickas.com)<br />[🐛](https://github.com/Venuu/jsonapi-authorization/issues?q=author%3Ajpalumickas) [💻](https://github.com/Venuu/jsonapi-authorization/commits?author=jpalumickas) [⚠️](https://github.com/Venuu/jsonapi-authorization/commits?author=jpalumickas) |
 <!-- ALL-CONTRIBUTORS-LIST:END -->
 
-This project follows the [all-contributors](https://github.com/kentcdodds/all-contributors) specification. Contributions of any kind welcome!
+This project follows the [all-contributors](https://github.com/kentcdodds/all-contributors) specification. Contributions of any kind welcome!