How to write documents for binary operators such as +, -, etc.

[kubo]

Look at the following code:

class NumericClass
  def +(other)
  end
end

I want (Object) <- self + other or so as a call-sequence, because "+" is a binary operator.
But I get (Object) +(other).
@overload self + other doesn't solve it. I get (Object) self(+other) by it.

How can I change the call-sequence that looks like an arithmetic binary operation?

[lsegal]

The short answer is we don't support this, though you could write a small plugin to override templates and have these signatures generated.

YARD tries to maintain consistency across the way it shows signatures for method names, so although some methods can be used as binary operators in the grammar, the documentation itself is still just method documentation. It's not really YARD's job to discuss the syntax of the Ruby language. We could have a separate distinction for operators, but I'm not sure it's worth it, nor is it strictly accurate. If we started showing varying signatures within the method summary, it would be visually awkward, I think. Part of the benefit of showing signatures in a consistent fashion is that users know what to expect, where to click, what information is relevant, etc.

If you really want to remind users that things like +, -, etc. are binary operators, using @example tags could do this. And of course, you can always just override HtmlHelper#signature (as mentioned above) in a plugin or loaded ruby file when generating documentation.

[kubo]

Thank you. I'll use @example tags.

Well, expert ruby developers will know that binary operations are syntax sugar of method calls. They can find what they seek. But what about novices?

[lsegal]

But what about novices?

This is an interesting question (and problem). You're right, novices might get confused by this. But they also might not. I'd love to interview some (new) Ruby users reading docs to find out what the sticking points are. Unfortunately, those users are harder to find. If you know any new users who want to get in touch with their personal feedback, I'd be super happy to listen. Personally, I'd like to think that the consistency that YARD provides will help, not hurt them. There are a lot of things documentation tools can provide, but there are also limitations. I think the signature line should detail the method and parameter names, possibly a return type, it should not detail how the method is used. I think that is better left for an example tag.