How to access keyword arguments in macro?

27 views
Skip to first unread message

en...@envek.name

unread,
Jun 5, 2018, 10:55:02 AM6/5/18
to YARD
Hi everyone.

I want to improve docs for dry-initializer and declare generated accessor methods in docs.

In this gem the name of the generated method to access attribute is taken from optional keyword argument.

So, having a definition of DSL method in dry-initializer gem:

module Dry
  module Initializer
    # Declares keyword argument
    #
    # @!macro [attach] option
    #   @!method $3
    #     Accessor for the +$1+ initializer option
    def option(name, type = nil, as: name, **opts)
      # some magic here
    end
  end
end

I want that for following code in my project:

class MyClass
  extend Dry::Initialzer

  option :class, as: :klass
end

And to use it as MyClass.new(class: "Foo").klass # => Foo

And nn docs klass method should be added, equivalent to following definition:

# @!method klass
#   Accessor for the +class+ initializer option

It doesn't work because many of the usages will omit second positional argument and order of keyword arguments can't be reliable too.

Is it possible to achieve that? How?

Thank you in advance.
With best regards,
Andrey Novikov.

Loren Segal

unread,
Jun 6, 2018, 1:16:36 AM6/6/18
to yar...@googlegroups.com

Hi,

Unfortunately macros only support positional arguments. Your better bet here would be to write a YARD plugin to handle this.

Plugin docs here: https://yardoc.org/guides/extending-yard/writing-handlers.html

You could publish a yard-dry-initializer plugin and use this to document your code. YARD automatically looks for gems with the `yard-` prefix (i.e. yard-FOO) and loads them if someone uses "--plugin FOO" in their .yardopts or command line options.

Note that a plugin would not only solve the use case for your own codebases, but it would allow your library's users to take advantage of generated documentation in their own projects without having to mess with complicated macro declarations. It's an all around better solution even if you _could_ do this with macros.

Hope that helps,

Loren

--

---
You received this message because you are subscribed to the Google Groups "YARD" group.
To unsubscribe from this group and stop receiving emails from it, send an email to yardoc+un...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

en...@envek.name

unread,
Jun 11, 2018, 5:16:50 PM6/11/18
to YARD
Hi, Loren!

Thank you very much for telling me about YARD plugins and providing a link to very easy to read and motivating manual about how to write handlers.

I've published a preview of yard-dry-initializer gem: https://github.com/Envek/yard-dry-initializer (code cleanup, full set of specs and battle testing are pending)

среда, 6 июня 2018 г., 8:16:36 UTC+3 пользователь Loren Segal написал:
Reply all
Reply to author
Forward
0 new messages