Document Model Attributes with Yard

Document model attributes with YARD

After quite a while searching around, I punted and manually added the documentation for the attributes to the model files. This is certainly not ideal, but hopefully the model structure won't change a whole lot.

I created a .yardopts file for the project and used the yard command-line options to create two new tags for marking these up:

--type-name-tag 'attribute:Attributes' --type-name-tag 'association:Associations'

These provide me with specific tags for marking up the attributes and associations; they will show up grouped under the "Attributes" and "Associations" headings in the documentation. I can add this:

# @attribute name [String] The name of the object
# @association relatedObjs [Array<AnotherClass>] Objects needed to perform a certain function

Maybe someone will write a plugin for YARD that will parse out the annotate-models output.

YARD - how to document @!method YARD on class level rather than instance level?

This can be adjusted via @!scope which can be either class or instance:

class Foo
  # @!scope class
  #
  # @!method bar
  #   @return [Bar] enum scope
  # @!method baz
  #   @return [Baz] enum scope
end

See Documenting Custom DSL Methods

YARD doc - how to document a class type focusing on its parent class

It's sufficient to write

# @return [AbstractClass]

The reader should assume that Liskov substitution may apply. The Abstract prefix (as well as an @abstract tag) will also communicate this clearly, and the resulting documentation will list ConcreteClass1 and ConcreteClass2 under the "Direct Known Subclasses" of AbstractClass.

As for returning a class, the YARD creator's recommendation is to use Class<AbstractClass>.

How to document simple scripts with YARD?

Just document the methods in the script as you would for any class- or module-based methods. YARD should document them as part of the "Top Level Namespace".

The following modification to your script just works, removing the class String wrapper:

#!/usr/bin/env ruby -wKU

# Prints a string using two supplied strings
#
# @param str1 [String] A string to print
# @param str2 [String] A string to print
# @return [String] A printed string
def yardTest(str1, str2)
  p sprintf("Hello, %s, %s", str1, str2)
end   

You might also want to consider documenting the API of the script for its users, which is for a different purpose and audience of course.

Also do consider separating the command-line interface from the methods that perform actions - in which case you will end up creating suitable modules and classes. This is a natural pattern when making anything remotely complicated, and would allow you to share your logic between scripts in future, or perhaps into things that are not invoked from the command line. You could take a look at the thor gem - it is a framework for creating command-line scripts, and includes examples of command-line interfaces that follow a nice pattern of abstraction. Thor has support for easily including standard practice usage and help in a command-line script.

Best way to document splatted parameter with YARD?

YARD's creator, lsegal, states that the appropriate thing to do is provide an @overload for expected invocations. However, this doesn't really provide much clarity in the case of an Array#push-like method.

I suggest that you use the @param tag and use Array<Object> as the argument type or provide an @overload that looks nice.

Here's a comparison of the two:

class Test
  # A test method
  #
  # @param [Array<Object>] *args Any number of Objects to push into this collection
  # @return nil
  def push(*args); end

  # Another test method
  #
  # @overload push2(obj, ...)
  #   @param [Object] obj An Object to push
  #   @param [Object] ... More Objects
  def push2(*args); end
end

---

Related Topics