代码之家  ›  专栏  ›  技术社区  ›  Arnaud Leymet

在Ruby中以编程方式访问属性/方法注释

  •  4
  • Arnaud Leymet  · 技术社区  · 16 年前

    是否有一种以编程方式访问方法注释的方法?还是属性注释?

    我想用它来描述文档中的方法,我不希望它是静态的,或者用RDOC或等效的工具生成。

    下面是Ruby类的一个例子:

    Class MyClass
      ##
      # This method tries over and over until it is tired
      def go_go_go(thing_to_try, tries = 10) # :args: thing_to_try
        puts thing_to_try
        go_go_go thing_to_try, tries - 1
      end
    end
    

    基本上,我希望能够做到以下几点:

    get_comment MyClass.gogogo # => This method tries over and over until it is tired
    
    3 回复  |  直到 8 年前
        1
  •  13
  •   Jörg W Mittag    10 年前

    不,你不能这样做。

    整点 评论的重点是 不 计划的一部分!如果您想要一个字符串作为程序的一部分,只需使用一个字符串。

    在大多数Ruby实现中,注释已经在lexer中被丢弃,这意味着它们甚至不能到达 语法分析器 更不用说 口译译员 或编译器。在代码运行时,注释早已消失……事实上,在使用编译器的Rubinius或Yarv等实现中,根本没有办法将注释存储在已编译的可执行文件中,因此即使lexer或解析器没有丢弃这些注释,也会 仍然 无法将它们与运行时通信。

    所以,您唯一的机会就是解析Ruby源文件来提取注释。但是,正如我上面提到的,你不能只接受 任何 解析器,因为大多数现有的解析器都会丢弃注释。(这也是 整点 但是,Ruby解析器保留注释,尤其是在RDOC或Yard等工具中使用的注释。

    yard特别有趣,因为它还包含一个查询引擎,它允许您根据一些强大的谓词(如类名、方法名、yard标记、API版本、类型签名等)搜索和筛选文档。

    但是,如果你 做 最后使用RDOC或Yard进行解析,那么为什么不首先使用它们呢?

    或者,就像我上面建议的,如果您想要字符串,只需要使用字符串:

    module MethodAddedHook
      private
    
      def method_added(meth)
        (@__doc__ ||= {})[meth] = @__last_doc__ if @__last_doc__
        @__last_doc__ = nil
        super
      end
    end
    
    class Module
      private
    
      prepend MethodAddedHook
    
      def doc(meth=nil, str)
        return @__doc__[meth] = str if meth
        @__last_doc__ = str
      end
    
      def defdoc(meth, doc, &block)
        @__doc__[meth] = doc
        define_method(meth, &block)
      end
    end
    

    这给了我们一个方法 Module#doc 我们可以使用它来记录一个已经存在的方法,方法的名称和docstring调用它,或者您可以使用它来记录下一个定义的方法。它通过将docstring存储在临时实例变量中,然后定义 method_added 钩子,它查看该实例变量并将其内容存储在文档散列中。

    还有 Module#defdoc 一次定义和记录方法的方法。

    module Kernel
      private
    
      def get_doc(klass, meth)
        klass.instance_variable_get(:@__doc__)[meth]
      end
    end
    

    这是你的 Kernel#get_doc 收回文件的方法(或 nil 如果方法未经记录)。

    class MyClass
      doc 'This method tries over and over until it is tired'
      def go_go_go(thing_to_try, tries = 10)
        puts thing_to_try
        go_go_go thing_to_try, tries - 1
      end
    
      def some_other_meth; end # Oops, I forgot to document it!
    
      # No problem:
      doc :some_other_meth, 'Does some other things'
    
      defdoc(:yet_another_method, 'This method also does something') do |a, b, c|
        p a, b, c
      end
    end
    

    在这里,您可以看到记录方法的三种不同方法。

    哦,它起作用了:

    require 'test/unit'
    class TestDocstrings < Test::Unit::TestCase
      def test_that_myclass_gogogo_has_a_docstring
        doc = 'This method tries over and over until it is tired'
        assert_equal doc, get_doc(MyClass, :go_go_go)
      end
      def test_that_myclass_some_other_meth_has_a_docstring
        doc = 'Does some other things'
        assert_equal doc, get_doc(MyClass, :some_other_meth)
      end
      def test_that_myclass_yet_another_method_has_a_docstring
        doc = 'This method also does something'
        assert_equal doc, get_doc(MyClass, :yet_another_method)
      end
      def test_that_undocumented_methods_return_nil
        assert_nil get_doc(MyClass, :does_not_exist)
      end
    end
    

    注意:这是相当粗糙的。例如,没有锁定,因此如果两个线程同时为同一个类定义方法,文档可能会出错。(即:docstring可能是由于错误的方法导致的,或者丢失。)

    我相信 rake 对它做了本质上相同的事情 desc 方法,代码基是 许多的 比这更好的测试,所以如果你打算在生产中使用它,我会偷吉姆的代码而不是我的。

        2
  •  1
  •   Chris McCauley    16 年前

    注释(通常)被lexer丢弃,并且在执行时不能在Ruby的符号表中使用。 .

    我想你能做的最接近的就是

    (A)实现get-comment的方式是,它在运行时创建一个regex,并在源文件中搜索匹配项。你需要像这样改变你的语法…

     get_comment :MyClass, :go_go_go
    

    您可以将符号转换为字符串,假定源文件是myclass.rb,并在其中搜索comment-def-method_name模式的匹配项。

    (B)从每个构建全局注释表的源文件中调用一个方法。

    不管怎样,这是混乱的,比它的价值更麻烦。

        3
  •  0
  •   stwienert    8 年前

    同时,还有一块“标准”宝石 method_source 这就解决了一些问题:

    https://github.com/banister/method_source

    Set.instance_method(:merge).comment
    
    Set.instance_method(:merge).source
    

    它还配有最新的轨道( railties >= 5.0 )版本和由发动机罩下的撬棍使用。

    推荐文章