Established way to document Rails params hash in YARD

[Phil Darnowsky]

Hi all,

I've just thrown over RDoc for YARD in a Rails project I'm working on, and was wondering if anyone has any established conventions for documenting the effect of different parameters in the params hash. It seems like I could use the @options tag, but that feels a little hackish. Any suggestions?

Thanks,
Phil

[Dan Croak]

I'd go:

# @param [Hash] opts to do something cool

> --
> You received this message because you are subscribed to the Boston Ruby Group mailing list
> To post to this group, send email to boston-r...@googlegroups.com
> To unsubscribe from this group, send email to boston-rubygro...@googlegroups.com
> For more options, visit this group at http://groups.google.com/group/boston-rubygroup
>

[Dan Croak]

@option: Describe an options hash in a method. The tag takes the name of the
options parameter first, followed by optional types, the option key name, an
optional default value for the key and a description of the option.

# @param [Hash] opts the options to create a message with.
# @option opts [String] :subject The subject
# @option opts [String] :from ('nobody') From address
# @option opts [String] :to Recipient email
# @option opts [String] :body ('') The email's body
def send_email(opts = {})
end

cheat yard

http://cheat.errtheblog.com/s/yard/

[Gabriel Horner]

As a random side note, you can irb-autocomplete options for methods
you document with @option:
http://tagaholic.me/2010/05/19/documentation-generated-irb-autocompletions-with-bond-and-yard.html#yard_based_irb_autocompletions