Document the defaultCount argument for @paginate and @hasmany(#89)

nuwave/lighthouse#428

Author: georgeboot

docs/api-directives.md

@@ -382,24 +382,26 @@ type User {
 }
 ```
 
-You can return the related models paginated by setting the `type`.
+If the name of the relationship on the Eloquent model is different than the field name,
+you can override it by setting `relation`.
 
 ```graphql
 type User {
-  postsPaginated: [Post!]! @hasMany(type: "paginator")
-  postsRelayConnection: [Post!]! @hasMany(type: "connection")
+  posts: [Post!]! @hasMany(relation: "articles")
 }
 ```
 
-If the name of the relationship on the Eloquent model is different than the field name,
-you can override it by setting `relation`.
+You can return the related models paginated by setting the `type`.
 
 ```graphql
 type User {
-  posts: [Post!]! @hasMany(relation: "articles")
+  postsPaginated: [Post!]! @hasMany(type: "paginator")
+  postsRelayConnection: [Post!]! @hasMany(type: "connection")
 }
 ```
 
+Pagination for related models works just like for root fields, find out more about this in [`@paginate`](directives#paginate).
+
 ## @hasOne
 
 Corresponds to [Eloquent's HasOne-Relationship](https://laravel.com/docs/eloquent-relationships#one-to-one).
@@ -635,15 +637,44 @@ type Query {
 
 ## @paginate
 
-Return a paginated list. This transforms the schema definition and automatically adds
-additional arguments and inbetween types.
+Transform a field so it returns a paginated list.
 
 ```graphql
 type Query {
   posts: [Post!]! @paginate
 }
 ```
 
+The schema definition is automatically transformed to this:
+
+```graphql
+type Query {
+  posts(count: Int!, page: Int): PostPaginator
+}
+
+type PostPaginator {
+  data: [Post!]!
+  paginatorInfo: PaginatorInfo!
+}
+```
+
+And can be queried like this:
+
+```graphql
+{
+  posts(count: 10) {
+    data {
+      id
+      title
+    }
+    paginatorInfo {
+      currentPage
+      lastPage
+    }
+  }
+}
+```
+
 The `type` of pagination defaults to `paginator`, but may also be set to a Relay
 compliant `connection`.
 
@@ -653,7 +684,26 @@ type Query {
 }
 ```
 
-By default, this looks for an Eloquent model in the configured default namespace, with the same
+You can supply a `defaultCount` to set a default count for any kind of paginator.
+
+```graphql
+type Query {
+  posts: [Post!]! @paginate(type: "connection", defaultCount: 25)
+}
+```
+
+This let's you omit the `count` argument when querying:
+
+```graphql
+query {
+  posts {
+    id
+    name
+  }
+}
+```
+
+By default, Lighthouse looks for an Eloquent model in the configured default namespace, with the same
 name as the returned type. You can overwrite this by setting the `model` argument.
 
 ```graphql
@@ -664,7 +714,6 @@ type Query {
 
 If simply querying Eloquent does not fit your use-case, you can specify a custom `builder`.
 
-
 ```graphql
 type Query {
   posts: [Post!]! @paginate(builder: "App\\Blog@visiblePosts")