17

I'm using YARD to generate docs for my rails app with makrdown as the script parser. Most of the documentation features just work great right out of the box. However, I'd also like to document the model attributes to one, record the list of available attributes on a model and two, to describe their semantic meaning.

I wasn't able to find any special support for this in YARD and I'm basically left with simply listing out the attributes in the class comments. Is there a way to document the dynamically generated model attributes so that they appear in the documentation like standard attributes/methods?

P.S. I've used the annodate-models gem to generate a basic schema dump at the top of the class listing but that's not really what I want.

Paul Alexander
  • 31,970
  • 14
  • 96
  • 151

2 Answers2

18

It seems that YARD now has its own @!attribute (notice the exclamation mark) tag for this purpose:

http://rubydoc.info/docs/yard/file/docs/Tags.md#attribute

Example:

class Task < ActiveRecord::Base
  # @!attribute name
  #   @return [String] The name of the task.

  # @!attribute description
  #   @return [String] The description of the task.

  # @!attribute active
  #   @return [Boolean] Marks whether the task is active or not.
end

This will result in nice documentation of your attributes. The only thing to watch out is that you always keep your documentation up to date because nobody will check whether you remove an attribute from your documentation when you deleted it from the database, etc.

Joshua Muheim
  • 12,617
  • 9
  • 76
  • 152
  • 1
    That's the solution I used, but it has the problem that YARD shows `Task#name=`, `Task#description=` and `Task#active=` as undocumented, so I don't know how to get my documentation back up to 100%. – digitig Apr 01 '15 at 10:54
  • 1
    I ended up just duplicating the docs for setters. Is there a better solution? `@!attribute description=` – GreenEggs Aug 06 '15 at 21:58
11

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.

dmkash
  • 1,247
  • 9
  • 11
  • 1
    This looks promising. I've already forked the annotae-models gem to add additional formats. This might just be the way to go. Can you include the full command line and .yardopts file in a github repository? – Paul Alexander Apr 11 '11 at 17:18
  • 2
    YES! Just put all of the command-line options that you would use into the .yardopts file in your project root. Then all you have to do is run `yardoc` from your project root. I'd be interested to see what you come up with from the annotate-models code. There was an interesting fork that someone had that could pull comments from the MySQL tables along with the rest of the column information. That might make it even easier. – dmkash Apr 12 '11 at 02:18
  • This looks promising, but it seems YARD ignores the `[Type]`?! Have you come up with any other solution? How well did this work out for you? – Joshua Muheim Jul 26 '12 at 14:36
  • I found a better solution, see my answer below. – Joshua Muheim Jul 26 '12 at 15:45