Forum: Ruby yard custom tags

A665665c83ac8d18e9f36083db34e971?d=identicon&s=25 Charles Hixson (charlesh)
on 2013-09-01 22:37
(Received via mailing list)
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:in
`define_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:in
`block 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:in `block 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:in `parse_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:in `permute!'
     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:in
`parse_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:in
`parse_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:in
`parse_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:in
`run'
     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:in `load'
     from /usr/local/bin/yardoc:23:in `<main>'
Fa0f9fecf293ddbe3d0c64f6b4418440?d=identicon&s=25 Dan Rathbun (dan_rathbun)
on 2017-01-28 22:07
Charles Hixson 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.m...

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

~
Please log in before posting. Registration is free and takes only a minute.
Existing account

NEW: Do you have a Google/GoogleMail, Yahoo or Facebook account? No registration required!
Log in with Google account | Log in with Yahoo account | Log in with Facebook account
No account? Register here.