Lighthouse: Some directives are missing their arguments in the docs

[alberthaff]

Some of the directives are missing some of their arguments in the docs.

This includes:

• @all
• @first
• @paginate

[spawnia]

Hey, i would love to see a PR for that :)

[alberthaff]

I will go through the rest of them and make a PR tomorrow.

[alberthaff]

I think we may need to add a table to each directive with their arguments. It will easily get cluttered if we add multiple arguments to the snippets.

Something like this could make it easier to see which arguments are available on a directive:

@belongsTo

| Argument | Type | Default | Description |
| ------------- |:-------------:| :-----:| :----- |
| relation | String | | Select the method from which to fetch related models. |
| scopes | [String] | [] | Select which scopes to apply to the underlying query. |
| defaultCount | Int | Global setting used | Select the default count. |
| maxCount | Int | Global setting used | Select the max count. |

[spawnia]

Let's go for a formal directive definition in SDL. It has the added benefit that it can be
used for autocompletion and IDE help in the schema definition.

directive @paginate(
  """
  Which pagination style to use.
  Allowed values: paginator, connection.
  """
  type: String = "paginator"

  """
  Specify the model class to use.
  This is only needed when the default model resolution does not work.
  """
  model: String

  """
  Point to a function that provides a Query Builder instance.
  This replaces the use of a model.
  """
  builder: String

  """
  Apply scopes to the underlying query.
  """
  scopes: [String!]

  """
  Overwrite the paginate_max_count setting value to limit the
  amount of items that a user can request per page.
  """
  maxCount: Int

  """
  Use a default value for the amount of returned items
  in case the client does not request it explicitly
  """
  defaultCount: Int
) on FIELD_DEFINITION

I would like to include those descriptions in the Directive classes themselves actually.
That would enable us to add an export command that spits out those definitions for usage in the schema files.

[alberthaff]

That would be a great addition!

However, i think we should also add the arguments to the directives page, since some people probably won't install the JS-graphql plugin or use an IDE without graphql autocompletion.
I often see questions on Slack from people who don't know that certain arguments are available.

Should i add an abstract variable called $directiveSDL and define it in each directive on that variable (i'll create a separate PR for that)?

[spawnia]

Agreed, we should definitely do both.

Let's just add the definitions to the docs as a first step, while we figure out how we can include them in the directive classes.

Second step, i think we might add a method to the Directive interface to do it.

[alberthaff]

Okay. I'll add the arguments like this:

[spawnia]

@alberthaff let's just use a directive definition in SDL instead of that table. It has all the elements of the table, but is way more useful outside of the docs.

I don't want to duplicate efforts. That way, we can define it once and it can be used for all possible purposes, since it is a formal notation.

[alberthaff]

Alright. How do you want the layout? Like this?

@auth

Return the currently authenticated user as the result of a query.

type Query {
    me: User @auth
}

If you need to use a guard besides the default to resolve the authenticated user,
you can pass the guard name as the guard argument

type Query {
    me: User @auth(guard: "api")
}

SDL

SDL HERE

[spawnia]

How about something like this?

@directive

A one line description of the directives funtionality.

A basic example with the most common use.

Definition (we might have that formatted as bold, i don't want it in the sidebar)

The formal SDL definition

More examples, further explanation of the additional use cases/arguments

[alberthaff]

Perfect. Vuepress ignores h3 in the sidebar, so that is not a problem :-)