0

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?

David Ljung Madison Stellar
  • 3,008
  • 1
  • 26
  • 46

1 Answers1

0

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, i.e. 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 } → obj
  • 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.

Jörg W Mittag
  • 363,080
  • 75
  • 446
  • 653
  • I mean - that doesn't completely go against what I am asking. The 3rd and 4th examples would sometimes be written as multiple lines. And if the "block" portion of it was often portions of code that would be worth spelling out as a calling example, it would be nice to have multiple lines. I don't quite know what you mean about the "→". That's not part of the rdoc syntax as near as I can tell, that's just something you've decided to add to your call-seq strings, no? – David Ljung Madison Stellar Oct 28 '21 at 23:47