Add possibility to add custom examples for mutations and query arguments

[JonasEtzold]

Currently, I can only add custom examples to individual arguments of a query or mutation via the metadata JSON file or the spectaQL directive. In my case, I have a mutation where the presence of a certain argument depends on the value of another argument. Hence, the autogenerated examples do not make sense, and the easiest way to fix that is to provide custom examples on the mutation level within the metadata JSON file like this:

{
  "OBJECT": {
    "Mutation": {
      "fields": {
        "checkOut": {
          "documentation": {
            "examples": [...]
          }
        }
      }
    }
  }
} 

Right now, this gets ignored since it is not on args level. Is there any other way to achieve this?

[mortenpi]

This is semi-intentional I'd say. The first docstring is not really attached to a method, but attached to the binding itself. So with Trash.list we're just including the docstring of the binding. It's just that if you don't have any docstring on the binding (just methods), we include all the docstrings of that binding (kind of an autodocs-y feature, really).

The practical issue of always including all docstrings of a binding is that you'll lose the fine-grained control of being able to include just the binding.

Something that I have thought about is that we could maybe introduce is some way of annotating the binding name in the at-docs block such that it behaves differently (e.g. combine binding + methods; by having something like @all Trash.list or something).

[tecosaur]

I can see the sense in what you're saying, but I do consider it counterintuitive.

The way I know I (and I'm guessing other users of Documenter) thought about @docs name is that it showed all of the availible documentation of name from the target package, rather than just a certain sort of documentation that's usually the only type available.

I suppose the other aspect that makes this feel strange to me is that it's yet another difference from @doc in the Julia REPL. I know this has come up before, but I do think it would be good if the behaviour of Base.Docs and Documenter was more in sync (I'm aware that the Base.Docs code is a bit of a mess and this isn't easy, it just seems worth mentioning).

[mortenpi]

I suppose the other aspect that makes this feel strange to me is that it's yet another difference from @doc in the Julia REPL.

This is fair -- having those be consistent would be nice. But I am not sure at behavior of @doc is rigorously documented either?

Something to note though is that any of the changes here would be breaking. That said, if we strongly feel about it, I think we could add an option here and deprecate the default?

Just as a small actionable step, what could be valuable here is to articulate / document the rules of at-docs (including the differences from Base). The current docs are not particularly detailed. And then we could articulate exactly how the rules should work. Having things properly documented would help the discussion here. Some edge cases to consider are also docstrings on types, constructors, and the (::T)(...) call methods.

[tecosaur]

Something to note though is that any of the changes here would be breaking.

Yea, I almost feel bad tossing that comment out casually because I know it's not an easy thing. I just really like going by the principle of least surprise, and in that regard the more Documenter's @docs and @doc behave like each other the better I think.

Just as a small actionable step, what could be valuable here is to articulate / document the rules of at-docs

That would be an good clarification IMO, the first thing I did after being confused why my @doc "..." list(::String) docstring (& co.) weren't being shown was look at https://documenter.juliadocs.org/stable/man/syntax/#@docs-block, where I read:

This block type is evaluated within the CurrentModule module if defined, otherwise within Main, and so each object listed in the block should be visible from that module. [...] To ensure that all docstrings from a module [...]

and

Notice also that you can use @​docs to display the documentation strings of only specific methods, by stating the dispatch types.

Which together gave me the impression that @docs foo is expected to show all docstrings associated with foo, rather than the docstrings associated with defined methods of foo.

[tecosaur]

Just FYI I'm currently working around the behaviour with https://github.com/tecosaur/Trash.jl/commit/8297673fec8ba4ca705780251ee583e23f93ef1f, which is an awful kuldge but includes the docstrings as intended.

Before

After