使用Yard编写Rails项目文档

Question

我正在使用Yard生成文档，但我找不到任何ruby on rails项目的示例文档。我在rubydoc.info上只找到了一些简短的getting started tutorial和一些github项目，但它们根本没有文档记录。谁能告诉我如何正确地记录rails项目的控制器(带动作)、模型、路线

例如，我有这样的控制器：

class ArticlesController < ApplicationController
  before_filter :authenticate_user!, except: [:show]
  before_filter :restrict_user, only: [:edit, :update]

  def index
    @articles = current_user.articles.sort_by_rating.
        paginate(:page => params[:page],
                 per_page: 5)
  end

  def new
    @user = User.find(params[:user_id])
    @article = @user.articles.build
  end

  def create
    @user = User.find(params[:user_id])
    @article = @user.articles.build(params[:article])

    if @article.save
      redirect_to  @article, notice: 'Article was successfully created.'
    else
      render action: "new"
    end
  end
end

和用户模型：

class User < ActiveRecord::Base
  # Include default devise modules. Others available are:
  # :token_authenticatable, :confirmable,
  # :lockable, :timeoutable and :omniauthable :recoverable
  devise :database_authenticatable, :registerable,
         :rememberable, :trackable, :validatable

  # Setup accessible (or protected) attributes for your model
  attr_accessible :name, :email, :password, :password_confirmation, :remember_me
  # attr_accessible :title, :body

  validates_presence_of :name
  validates_uniqueness_of :name, :email, :case_sensitive => false

  has_many :articles, dependent: :destroy

  letsrate_rater
end

Answer 1

我知道这个问题有点老了，但我已经为attr_accessible创建了一个插件，其中包含从db/schema.rb中提取的数据类型。这个插件直接基于YARD::Handlers::Ruby::AttributeHandler

require 'active_support/inflector'
class AttrAccessibleHandler < YARD::Handlers::Ruby::AttributeHandler
  include ActiveSupport::Inflector
  handles method_call(:attr_accessible)
  namespace_only


  process do
    return if statement.type == :var_ref || statement.type == :vcall
    read, write = true, true
    params = statement.parameters(false).dup
    hashify_object_types(underscore(namespace.name).pluralize)
    # Add all attributes
    validated_attribute_names(params).each do |name|
      namespace.attributes[scope][name] ||= SymbolHash[:read => nil, :write => nil] #Comment this out to see getter and setter methods

      # Show their methods as well
      {:read => name, :write => "#{name}="}.each do |type, meth|
          object_type = attribute_type(name)
          o = MethodObject.new(namespace, meth, scope)
          if type == :write
            o.parameters = [['value', nil]]
            src = "def #{meth}(value)"
            full_src = "#{src}\n  @#{name} = value\nend"
            doc = "Sets the attribute #{name}\n
                   @param [#{object_type}] value the value to set the attribute #{name} to."
          else
            src = "def #{meth}"
            full_src = "#{src}\n  @#{name}\nend"
            doc = "@return [#{object_type}] #{name}\nReturns the value of attribute #{name}"
          end

          o.source ||= full_src
          o.signature ||= src
          o.docstring = doc if o.docstring.blank?(false)
          register(o)

          # Regsiter the object explicitly
          namespace.attributes[scope][name][type] = o #Comment this out to see getter and setter methods
      end
    end
  end
  def hashify_object_types(table)
    table_section = ""
    inside = false
    File.open("db/schema.rb").each do |line|
      if line =~ /create_table "#{table}"/ || inside == true
        inside = true
        table_section << line.chomp
        break if line.chomp.strip == "end"
      end
    end
    @hash_table = convert_keys(Hash[table_section.scan(/t\.(\w+)\s+"(\w+)"/).map(&:reverse)])
  end
  def attribute_type(name)
    @hash_table[name] || "Object"
  end
  def convert_keys(h)
    h.each_with_object({}) do |(k,v),obj|
      obj[k] = v == "datetime" ? "DateTime" : v.capitalize
    end
  end
end

这就假设您的插件位于根目录中，并且您有一个db/schema.rb文件。它也不会处理表名不是带下划线的复数字符串的类。BookAuthor #=> book_authors

Answer 2

我想像这样的东西对你来说是可行的。但我不是100%确定你的问题是什么。

class ArticlesController < ApplicationController
  before_filter :authenticate_user!, except: [:show]

  def index
    @articles = current_user.articles.sort_by_rating.
        paginate(:page => params[:page],
                 per_page: 5)
  end

  def new
    #I think this is self explanatory. 
    @article = Article.new
  end

  def create
    #devise has the user id with current_user and rails will do the job for you. 
    @article = current_user.articles.build(article_params)

    if @article.save
      redirect_to  @article, notice: 'Article was successfully created.'
    else
      render action: "new"
    end
  end

end

文章模型，看起来像这样

class Article < ActiveRecord::Base

  #Remember Rails 4 does use attr_accessible on the model
  attr_accessible :title,  :body, :user_id

  #Article belongs to user
  belongs_to :user

  #Here we can validate presense of these fields.
  validates :title, :body, :user_id, :presence => true


end

用户模型。

class User < ActiveRecord::Base
  # Include default devise modules. Others available are:
  # :token_authenticatable, :confirmable,
  # :lockable, :timeoutable and :omniauthable :recoverable
  devise :database_authenticatable, :registerable,
         :rememberable, :trackable, :validatable

  # Setup accessible (or protected) attributes for your model
  attr_accessible :name, :email, :password, :password_confirmation, :remember_me
  # attr_accessible :title, :body

  validates_presence_of :name
  validates_uniqueness_of :name, :email, :case_sensitive => false

  #relationship with the article
  has_many :articles, dependent: :destroy

  letsrate_rater
end

如果您正在询问如何记录您的项目，请尝试Yard。或者使用RDoc，您可以使用以下内置的Rake任务将其转换为浏览器友好的http://yardoc.org/：

$ rake doc:app