标签: yard

我正在使用码来从rdoc文件生成Rails应用程序的文档.有AngularJS文档生成器,但它们如何连接以生成AngularJS + Rails应用程序的一个连贯文档？

我正在使用YARD为我的ruby gem编写文档.在我的gem中,我有一些代码遵循这个常见的ruby模式,其中一个模块包含在一个类中,该模块不仅添加了实例方法,还添加了类方法:

module Moo
  def self.included(klass)
    klass.extend ClassMethods
  end

  module ClassMethods
    def hello
      puts "hello"
    end
  end
end

class Foo
  include Moo
end

Foo.hello  # => class method runs, printing "hello"

默认情况下,YARD将生成Foo类的文档,如下所示:

我认为这个文档是不合适的,因为它没有告诉用户该Foo.hello方法是可用的.要了解hello,用户必须单击Moo,然后单击ClassMethods.

Foo在一个页面上拥有所有类和实例方法的列表会很棒.我怎么能做到这一点？我是否需要更改代码,或者是否有我可以添加的标签给YARD一个提示ClassMethods？

在YARD自述文件中,提到raw dataYARD生成的:

YARD还将记录的对象输出为原始数据(转储的命名空间),可以将其重新加载以便在以后生成,甚至可以在代码上进行审计.这意味着任何开发人员都可以使用原始数据为任何自定义格式(例如YAML)执行输出生成.

什么是使用raw data和将其翻译成其他格式的示例/博客/教程？例如,我有兴趣将原始数据的一部分转换为YAML.

我想使用Yard链接到README中的另一个额外文件.

例如,我有以下行:

    ...detailed instructions [here](contributing.md) on how to contribute

我希望这链接到contributing.md同一目录中的文件.我可以在我的.yardopts文件中包含额外的文件,它将显示在文件列表中.

那么我发现我可以使用码DSL来使链接工作:

    ...detailed instructions {file:contributing.md here} on how to contribute

但是,如果从Github读取README,这将不起作用.我想要两种方式都天真吗？

有没有办法.md使用Yard 链接到markdown中的另一个额外文件？

如何使用YARD 创建指向ruby 类方法的链接？这是关于链接的院子文件.

链接到同一名称空间中的实例方法:

{#my_instance_method}

哪个工作正常.但是,遵循相同的方法与类方法不编译,并修改它:

{#self.my_class_method}

生成以下纯文本(不是链接):

ObjectName#self#self.my_class_method

我有一个方法应该采用任何类的1+参数,类似于Array#push:

def my_push(*objects)
  raise ArgumentError, 'Needs 1+ arguments' if objects.empty?
  objects.each do |obj| 
    puts "An object was pushed: #{obj.inspect}"
    @my_array.push obj
  end
end

使用YARD语法记录方法参数的最佳方法是什么？

编辑:

我意识到我原来的问题有点过于模糊,并没有明确说明我在寻找什么.

一个更好的问题是,当使用splatted参数时,在YARD中指定方法的arity(在这种情况下为1-∞)的最佳方法是什么？我知道我可以在文本中指定它,但似乎应该有一个标签或类似的东西来指定arity.

有没有办法告诉Yard不要弄乱我的Rails项目的doc/文件夹？我希望它保存文件doc/yard/或类似的东西.可悲的是,我没有找到任何选择.

谢谢你的帮助.

我有一个使用Forwardable模块中的def_delegators方法的类.我还没有办法让Yardoc为它输出文档.我尝试过使用宏但它不会为这些特定方法输出任何内容(文件中的其他内容都很好,并且没有错误),而且我有几个不同的长度.def_delegators

例如

class A
  extend Forwardable
  # other code…

  # @!macro
  #   @see Array#$1
  #   @see Array#$2
  #   @see Array#$3
  def_delegators :@xs, :size, :<<, :blah # …

如果有人知道宝石或这样做的方式,这意味着我可以避免尝试写Yard扩展来做到这一点,我将非常感激.

我有一个典型的OO模式:一个基本抽象类(定义抽象方法)和几个以类特定方式实现这些抽象方法的类.

我习惯在抽象方法中只编写一次文档,然后它自动传播到几个具体的类(至少它在Javadoc,Scaladoc,Doxygen中以下面的方式工作),即我不需要重复相同的描述在所有具体课程中.

但是,我无法找到如何在YARD中进行此类传播.我试过,例如:

# Some description of abstract class.
# @abstract
class AbstractClass
  # Some method description.
  # @return [Symbol] some return description
  # @abstract
  def do_something
    raise AbstractMethodException.new
  end
end

class ConcreteClass < AbstractClass
  def do_something
    puts "Real implementation here"
    return :foo
  end
end

我得到了什么:

• 代码按预期工作 - 即throws AbstractMethodException在抽象类中调用,在具体类中完成
• 在YARD中,AbstractClass明确定义为抽象,ConcreteClass是正常的
• 方法描述和返回类型都很好 AbstractClass
• 方法是说扔AbstractMethodException在AbstractClass
• 方法根本没有描述和泛型Object返回类型ConcreteClass,没有一个通知表明基类中存在抽象方法.

我期望获得:

• 方法的描述和返回类型ConcreteClass从info at 继承(即复制)到AbstractClass
• 理想地,该方法在"继承"或"实行"的部分中指定ConcreteClass的描述中,与来自一些参考链接ConcreteClass#do_something到AbstractMethod#do_something …

我有一个类,我从这样的工厂函数创建:

Cake = MyProject.Struct(:type, :price)

在Yard中,它只是与我的常量一起显示:

Cake =

        Struct(:type, :price)

我希望它出现在"Classes:"列表中.在阅读完文档之后,我开始相信这会起作用:

# @!parse class Cake; end
Cake = MyProject.Struct(:type, :price)

但它确实没有改变任何东西.

是否有可能让Yard将动态创建的类记录为类？