Question

I’m really new to this, and I’ve been going through the YARD docs, and haven’t really been able to figure out a solution to my problem.

Here is the code I’m starting with: https://github.com/spape/yard-rest-plugin which works great, but I’m trying to add some functionality to it.

Basically, I’m trying to add a filter such that I can include some Model documentation such that people looking through the Controller API docs can see what attributes of the Model they can use.

The plugin, yard-rest filters out any methods that don’t have the @resource tag. So, I figured, I’d add a @resource_object tag, for my Models, that I want to show certain information about in the API docs.

In the plugin’s code. I found in /lib/yard-rest.rb

YARD::Templates::Template.extra_includes << RestFilters

and in that file, I’ve modified the reject_without_resource(list) method

  def reject_without_resource(list)
    if list
      list.delete_if { |object| 
        if !object.is_a?(YARD::CodeObjects::ClassObject)
          true
        else
            !object.meths.detect{ |x| x.has_tag?(:resource) }# and 
          #  !object.detect{ |x| x.has_tag?(:resource_object) }
        end
      }
    end
  end

object is a YARD::CodeObjects::ClassObject in the cases that we care about. object.meths is an array of methods (Method Objects). and the Method Objects have a detect method, which allows to test if a method has whatever tag we want to test for via the .has_tag? call. But, I’ve been unable to find something similar for the class level. Right now, because I don’t want to document any methods in the models for the API Docs, I don’t want to put the @resource tag on any of the model methods.

My current .yardopts file, to show that I am indeed searching over models and controllers:

--title "My API Documentation"
--plugin rest
--readme API_README
app/models/*.rb
app/controllers/*.rb

So, how do I change the filter, such that I can include the models? Or at least class-level tags?

Answer 1

Turns out, you can call .has_tag on object.

If you just rearrange what you have to look like this:

def reject_without_resource(list)
    if list
      list.delete_if { |object|
        if object.has_tag?(:resource_object)
          false
        elsif object.meths.detect{ |x| x.has_tag? (:resource) }
          false
        else
          true
        end
      }
    end
  end

it will work