Forum: Ruby Metaprogramming and rdoc

Announcement (2017-05-07): www.ruby-forum.com is now read-only since I unfortunately do not have the time to support and maintain the forum any more. Please see rubyonrails.org/community and ruby-lang.org/en/community for other Rails- und Ruby-related community platforms.
fugalh (Guest)
on 2005-11-16 19:45
(Received via mailing list)
I find myself metaprogramming in ruby more and more. I think this is a
good thing. It also has the unfortunate side effect of pitting me
against my old friend rdoc. I want to document the methods, but rdoc
has no clue that they even exist. Is there some middle ground, or must
one just put it in the class's blurb, or give in to not
metaprogramming?

A simple example:

Class Foo
  # Methods that do just about the same thing
  %w{foo bar baz quux}.each do |m|
    eval "def #{m}(*args); something_interesting(m.to_sym,*args); end"
  end
end

Rdoc of course knows nothing, but I may have something interesting to
say about this group of methods as a whole.
zdennis (Guest)
on 2005-11-16 19:54
(Received via mailing list)
Hans F. wrote:
>   # Methods that do just about the same thing
>   %w{foo bar baz quux}.each do |m|
>     eval "def #{m}(*args); something_interesting(m.to_sym,*args); end"
>   end
> end
>
> Rdoc of course knows nothing, but I may have something interesting to
> say about this group of methods as a whole.

My first guess(es) would be:
  - document the functionality in your class documentation
AND/OR
  - use/write a code generator to generate rdoc-able ruby code with the
method annotations as the method comments in the outputted ruby code,
which would be picked up by rdoc

Zach
ara.t.howard (Guest)
on 2005-11-16 20:24
(Received via mailing list)
On Thu, 17 Nov 2005, Hans  Fugal wrote:

>  # Methods that do just about the same thing
>  %w{foo bar baz quux}.each do |m|
>    eval "def #{m}(*args); something_interesting(m.to_sym,*args); end"
>  end
> end
>
> Rdoc of course knows nothing, but I may have something interesting to
> say about this group of methods as a whole.

put a hook into your methods that spews out a docstring into a file.
run your
tests, then run rdoc over this file.  take the hook out.

another approach

   #
   # doccumentation
   #
   def meta_methods
     # empty
   end

-a
vjoel (Guest)
on 2005-11-16 23:10
(Received via mailing list)
Hans F. wrote:
>   # Methods that do just about the same thing
>   %w{foo bar baz quux}.each do |m|
>     eval "def #{m}(*args); something_interesting(m.to_sym,*args); end"
>   end
> end
>
> Rdoc of course knows nothing, but I may have something interesting to
> say about this group of methods as a whole.
>

This won't help with programmatically generating rdoc comments, if
that's what you want. But:

* define a class method ("my_interesting_accessor") that does your eval

* call the class method separately for each of foo bar .... (a little
more painful than a loop, but you've got to do it anyway if you want to
type out separate documentation for each)

* put docs above each of these as you wish

* use the -A my_interesting_accessor option to rdoc, and it will
recognize these comments

(It's not just for accessors, but that was the original use that I
proposed and Dave implemented. It really works for any class method that
has the same syntax as accessor definitions.)

$ rdoc --help | grep -A2 accessorname | ruby -pe 'sub!(/^ {6,12}/, "")'
--accessor, -A accessorname[,..]
                comma separated list of additional class methods
                that should be treated like 'attr_reader' and
                friends. Option may be repeated. Each accessorname
                may have '=text' appended, in which case that text
                appears where the r/w/rw appears for normal accessors.
This topic is locked and can not be replied to.