Yard custom tags

Ruby
1

How does one create a custom tag for yard? Any examples? Searches
haven’t been very useful.
What I’m after is a tag that I can use to document variables, especially
within a class, though documenting any in the global namespace would
also be useful. It would be nice if it were line a clone of @param,
that just appeared under a heading of “Variables” rather than, say,
parameters. And of course it would need to be under the class rather
than under the method.

I’ve tried placing variations of:
–tag “@var”:“variable for internal to class access only”
in my .yardopts file as the documentation appears to suggest, but this
is clearly wrong as what happens is variations of:

/usr/local/lib/ruby/gems/2.0.0/gems/yard-0.8.7/lib/yard/tags/library.rb:167:in
class_eval': /usr/local/lib/ruby/gems/2.0.0/gems/yard-0.8.7/lib/yard/tags/library.rb:167: syntax error, unexpected '(', expecting :: or '.' (SyntaxError) def @var_tag(text) ^ from /usr/local/lib/ruby/gems/2.0.0/gems/yard-0.8.7/lib/yard/tags/library.rb:167:indefine_tag’
from
/usr/local/lib/ruby/gems/2.0.0/gems/yard-0.8.7/lib/yard/cli/yardoc.rb:476:in
add_tag' from /usr/local/lib/ruby/gems/2.0.0/gems/yard-0.8.7/lib/yard/cli/yardoc.rb:719:inblock in tag_options’
from /usr/local/lib/ruby/2.0.0/optparse.rb:1364:in call' from /usr/local/lib/ruby/2.0.0/optparse.rb:1364:inblock in
parse_in_order’
from /usr/local/lib/ruby/2.0.0/optparse.rb:1351:in catch' from /usr/local/lib/ruby/2.0.0/optparse.rb:1351:inparse_in_order’
from /usr/local/lib/ruby/2.0.0/optparse.rb:1345:in order!' from /usr/local/lib/ruby/2.0.0/optparse.rb:1437:inpermute!’
from /usr/local/lib/ruby/2.0.0/optparse.rb:1459:in parse!' from /usr/local/lib/ruby/gems/2.0.0/gems/yard-0.8.7/lib/yard/cli/command.rb:55:inparse_options’
from
/usr/local/lib/ruby/gems/2.0.0/gems/yard-0.8.7/lib/yard/cli/yardoc.rb:502:in
optparse' from /usr/local/lib/ruby/gems/2.0.0/gems/yard-0.8.7/lib/yard/cli/yardopts_command.rb:96:inparse_yardopts’
from
/usr/local/lib/ruby/gems/2.0.0/gems/yard-0.8.7/lib/yard/cli/yardopts_command.rb:40:in
parse_arguments' from /usr/local/lib/ruby/gems/2.0.0/gems/yard-0.8.7/lib/yard/cli/yardoc.rb:272:inparse_arguments’
from
/usr/local/lib/ruby/gems/2.0.0/gems/yard-0.8.7/lib/yard/cli/yardoc.rb:237:in
run' from /usr/local/lib/ruby/gems/2.0.0/gems/yard-0.8.7/lib/yard/cli/command.rb:13:inrun’
from
/usr/local/lib/ruby/gems/2.0.0/gems/yard-0.8.7/bin/yardoc:12:in <top (required)>' from /usr/local/bin/yardoc:23:inload’
from /usr/local/bin/yardoc:23:in `’

2

Charles H. wrote in post #1120290:

What I’m after is a tag that I can use to document variables, especially
within a class, … It would be nice if it were line a clone of @param,
that just appeared under a heading of “Variables” rather than, say,
parameters. And of course it would need to be under the class rather
than under the method.

In Ruby this is usually done with attributes (which are actually
instance variables,) that are exposed via getter and/or setter instance
methods.

There is no reason to publicly document internal variables, that are not
exposed to consumers as attributes.

(A simple command line line tag creation is usually for filtering.
You couldn’t “invent” a variable listing with only a custom tag.)

In YARD attributes are documented with the @!attribute directive.

@!attribute [r] count

@return [Fixnum] the size of the list

See the YARD tags overview:
http://www.rubydoc.info/gems/yard/file/docs/Tags.md#attribute

There are two summaries and two method lists for attributes: class and
instance. You can change the scope using the @!scope directive.
http://www.rubydoc.info/gems/yard/file/docs/Tags.md#scope

You can also use the @!parse directive to be sure that YARD registers
attributes. See the example under:
http://www.rubydoc.info/gems/yard/file/docs/Tags.md#parse

~