Techioz Blog

rdoc で匿名クラスのドキュメントを生成することはできますか?

概要

rdoc の匿名クラスのいくつかのメソッドを文書化したいと思います。

yard などの代替の文書作成ツールが存在することは知っていますが、プロジェクト オーナーが、いくつかの方法のために在庫を変更する準備ができているかどうかはわかりません。

:method: と :doc: ディレクティブを試しましたが、今のところうまくいきません

Ruby 2.7、Rdoc 6.6.2で試してみた

# (c) 2024 Big Corporation

# = ExampleModule gives a great example to all of us
#
# This module contains an example of documenting an anonymous class created with Class.new.
module ExampleModule

  # Create an anonymous class using Class.new, almost the same as
  #   class AnonymousClass
  # and give a closure
  # but fails rdoc
  AnonymousClass = Class.new do
    ##
    # :method: initialize
    # This is a initializer with two parameters
    def initialize(param1, param2)
      # ... initialization code ...
    end

    ##
    # :method: example_method
    # == example_method
    #
    # An example method in the anonymous class.
    def example_method
      # ... method implementation ...
    end
  end
end

解決策

どうやら、私の例のメソッド コメントが AnonymousClass 定義の前に移動された場合、それらは (同じ HTML ページ内に) 表示されるようです。もちろん、クラスは検索可能ではないため、メソッドがモジュールではなくクラスに関連していることを明確にするためにいくつかのコメントが必要です。

# (c) 2024 Big Corporation


# This module contains an example of documenting an anonymous class created with Class.new.
module ExampleModule

  # documentation for methods for Anonymous Class
  # is given ahead of class definition to fool rdoc  

    ##
    # :method: an example_method of AnonymousClass
    #     
    # An example method in the anonymous class.

    ##
    # :method: initialize
    # This is an AnonymousClass initializer with two parameters

  # Create an anonymous class using Class.new, almost the same as
  #   class AnonymousClass
  # and give a closure
  # but fails rdoc
  # =class Anonymous Method
  AnonymousClass = Class.new do
    def initialize(param1, param2)
      # ... initialization code ...
    end

    ##
    # :method: example_method
    #     
    # An example method in the anonymous class.
    def example_method
      # ... method implementation ...
    end
  end
end

注記。実際のコードでは、rdoc 定数セクションに AnonymousClass の記述を追加することさえできませんでしたが、上記の小さな例では問題なく動作しているようです。しかし、一定のスキップには、これは必要ではない関連する問題が必要になる可能性があると思います。