坚持使用 rdoc：有什么方法可以为 call-seq 添加缩进？

Question

I know I should use YARD. Not an option in this environment.

So I'm using rdoc and call-seq is generally been great, but I want to add indentation for a call-seq that is always used in a block/yield style, something like:

call-seq:
    someFunc {
        example1(..)
        example2(..)
    }

But call-seq: removes any indentation and it becomes:

    someFunc {
    example1(..)
    example2(..)
    }

Which is sad. I know I could use a separate code block as an example, but this is really part of the general API for how this should be called, and it would be nice if I could use call-seq (instead of the ugly inverted colors of a code block).

I am guessing this isn't possible with the limitations of rdoc, but I thought I'd ask. Any thoughts?

Answer 1

I think you are confused about what the purpose of the calling sequence is, but the name unfortunately is really confusing. Normally, I would assume that it was designed by a non-native speaker, but if I remember my history correctly, RDoc was designed by David Thomas and Andy Hunt for their book Programming Ruby in 2000.

Anyway, calling sequence is not for documenting a sequence of calls , as one might surmise, ie it is not for documenting multiple lines of code.

It is for documenting what we could all in other languages multiple overloads of the method. Note that the syntax that is used for each overload is not even legal Ruby syntax (because of the → ), so treating it as executable code that is to be indented does not make much sense:

• inject(initial, sym) → obj
• inject(sym) → obj
• inject(initial) { |memo, obj| block } inject(initial) { |memo, obj| block } → obj
• inject { |memo, obj| block } inject { |memo, obj| block } → obj

What this tells us is that the Enumerable#inject method has four different "overloads", 2×2 combinations: with or without initial value and specifying the binary operation either as a block or as a Symbol .

Hence why it is not possible to format code inside the calling sequence.