Question

I want to write documentation for a method using Tomdoc. I have a method using a block by calling yield.

I don’t know how I should document it. Should I add a &block argument to my method even if I don’t use the variable itself, so I can list it in the method arguments ? Or should I write it in a different way with tomdoc ?

Thanks !

Answer 1

Use &block only if you have to as the overhead of creating it can be significant and that can cause issues if this method is called very frequently.

Generally it’s best to document that the method in question can take a block and always be specific about how that block is used. Since Ruby blocks are not usually passed in as specific arguments, the &block notation is only useful if you’re consistently capturing the block for later use or forwarding it through to another method.

Be sure to clearly communicate in your documentation if the block is required or optional. Putting it in the arguments explicitly implies it’s required.