2

In one file I have

module Adapter
  ##
  # :method: avatar

  ##
  # :method: avatar=(value)
end

In another file I want to have links to these methods:

# Adapter#avatar         # this generates a valid link to another page
# Adapter#avatar=        # this is shown as raw text

How to tell rdoc that it should generate the second link?

Update: it's confirmed that if the writer is defined statically with def avatar=(value); end, the link is generated okay. Dynamic writer though is apparently bugged.

Update2: Okay, it's not about the link. It's about generating right name of the writer method:

module Adapter
  ##
  # :method: avatar=(value)
end

generated doc with avatar=(value)() name, and

module Adapter
  def avatar=(value); end
end

generates correct avatar=(value) doc which gets linked.

ujifgc
  • 2,215
  • 2
  • 19
  • 21

1 Answers1

2

You should declare your parameters using :call-seq:, and not include your parameter list in the :method: line. The following works for me, and all the links work:

module Adapter
  ##
  # :method: avatar

  ##
  # :method: avatar=
  #
  # :call-seq: avatar=(value)
end

# See Adapter#avatar  
# See Adapter#avatar=
#
class Linked
end

:method: declares the name of the method, and :call-seq: declares the parameter signature it accepts.

(And BTW, I found some very helpful documentation on RDoc syntax here).

Stuart M
  • 11,458
  • 6
  • 45
  • 59
  • I can't define the method, it's dynamic. And the one without '=' is linked fine. – ujifgc Apr 11 '13 at 16:32
  • @ujifgc you can, but make sure you declare before dynamic generation happens. Dynamic generation (define_method for example) can overrode these empty methods... – Gabor Garami Apr 11 '13 at 17:26
  • So I define one method for rdoc and then dynamically create another one with different name, and I get two methods where I must have only the dynamic one. Right? – ujifgc Apr 12 '13 at 05:27
  • Aha, I think I got it. You need to use `:call-seq:`, and that makes all the links work and the methods show up without extra `()` characters. I've rewritten my answer, please check again – Stuart M Apr 12 '13 at 16:27
  • I would also mention, if you're just starting to write documentation and are interested in alternatives, I really prefer [YARD](http://yardoc.org) over RDoc. – Stuart M Apr 12 '13 at 16:34
  • 1
    Excellent, `:call-seq:` fixed everything. – ujifgc May 05 '13 at 07:00