[RFC] Replicate types hints to DSL methods

[amomchilov]

The auto-complete experience on the DSL methods (such as in RubyMine) is quite poor, because a lot of them just accept *args, **kwargs, &block.

I suggest we add type hints to the DSL methods. Sure, this causes duplication, and isn't DRY, but I think the benefit to IDE quick documentation and auto-completion is worth it.

I've done it for field as a sample.

WDYT?

[rmosolgo]

Thanks for the suggestion. I'd love to support IDEs better (I don't use one though), but I agree, this approach is unmaintainable in the long term.

I can think of a few approaches:

• Use Sorbet types (would that work in RubyMine?)

• Leverage YARD to make this work:

  • Expand def field(...) to name all incoming kwargs, and add docs for them, and pass them all along by name (yuck)
  • Add some kind of test to make sure that YARD doesn't spot any missing docs for that method or any orphaned documentation

  I say to use YARD, but maybe the thing could be accomplished another way, with a regexp linter? (I don't think Rubocop works on comments.)

  In theory, we could address all the current YARD warnings in the build and then add a test to make sure there aren't any new YARD warnings, but I think there are a lot of warnings to fix 🙈

Can you think of any other more maintainable approaches, or does either of those stand out to you?

[amomchilov]

Use Sorbet types (would that work in RubyMine?)

There's a Sorbet plugin for VS Code, but not Rubymine, I'm afraid. There's an open feature request: https://youtrack.jetbrains.com/issue/RUBY-21793

Expand def field(...) to name all incoming kwargs, and add docs for them, and pass them all along by name (yuck)

While that would be a little more verbose and repetitive than desired, I don't think it's actually that bad. If there's any intermediate layers of forwarding, those would be internal and wouldn't need the same level of the documentation.

I actually get the feeling that the doc comment should be removed from GraphQL::Schema::Field#initialize (is any consumer of this gem expected to call this initializer?), and kept solely on the public DSL APIs.

Re: yard tooling

I think that'll be more difficult than it's worth. RBS and Sorbet are going to come and save us soon enough, if we can just hold on.

[rmosolgo]

Ahh, too bad about sorbet not being supported yet. I'm game to include parameter documentations like you recommend here, but I'd like to keep them in def initialize, too, since that's where the keywords are actually used. I find the documentation helpful from time to time when I'm working on those methods.