custom_tags.rb

module YARD
  module Tags
    ##
    # Used to document requests to controllers. This processor provides a link 
    # to documentation about the particular type of HTTP request made. We use 
    # the W3C HTTP 1.1 (RFC2616) as a target for HTTP documentation. The 
    # recognized verbs by this class are GET, PUT, POST, DELETE.
    #
    # Sample format for using the request tag are as follows:
    #
    #   @request [GET] /people
    #   @request [POST] /pets
    #
    # @see http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html
    class RequestTag < Tag
      attr_reader :http_verb, :controller_url, :docstring
      undef_method :to_s, :inspect

      DOC_URL = "http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html"

      HTTP_VERBS = {
        "GET"    => "sec9.3",
        "PUT"    => "sec9.6",
        "POST"   => "sec9.5",
        "DELETE" => "sec9.7"
      }

      def initialize(tag_name, text, raw_text)
        super(tag_name, nil)
        parse_tag(raw_text)
      end

      def inspect
        "#<yardoc request #{path}>"
      end

      # @return [String] the URL of the HTTP verbs reference for this tag's 
      #   particular HTTP verb
      def reference_url
        [DOC_URL, HTTP_VERBS[http_verb]].join("#")
      end

      def type
        object.type
      end

      def object=(value)
        super(value)
        docstring.object = value
      end

      def tag(name) docstring.tag(name) end
      def tags(name=nil) docstring.tags(name) end
      def has_tag?(name) docstring.has_tag?(name) end

      def method_missing(sym, *args, &block)
        object ? object.send(sym, *args, &block) : super
      end

      private

      def parse_tag(raw_text)
        if md = raw_text.match(/^\[(#{HTTP_VERBS.keys.join('|')})\] (.+)$/)
          @http_verb      = md[1]
          @controller_url = md[2]
          @docstring      = Docstring.new(text, nil)
        end
      end

      def section_url(verb)
        [DOC_URL, HTTP_VERBS[verb]].join("#")
      end
    end

    class Library
      define_tag "Controller request",  :request,  RequestTag
      define_tag "Controller response", :response, :with_types
    end # Library
  end # Tags
end # YARD