1

I am documenting a project and essientially I have something similar to the following:

def foo
  return bar(__method__)
end

def bar (method)
 return method.to_s + 'somestring'
end

I am setting up a multitude of methods similar to how I have implemented foo where they are they are returning the return of bar. An example is as follows:

# The descriptions for foo0...
# @return [String] the method name concatenated with somestring
def foo0
  return bar(__method__)
end
# The descriptions for foo1...
# @return [String] the method name concatenated with somestring
def foo1
  return bar(__method__)
end

# The descriptions for bar...
# @return [String] the method name concatenated with somestring
def bar (method)
 return method.to_s + 'somestring'
end

But say I change what bar is returning to an integer then my documentation is incorrect. I familiar with documenting DSLs in YARD but how do you just specify #bar@return.type the return type of The return of method bar when describing another method. An example of what I am referring to is as follows:

# The descriptions for foo0...
# @return [#bar@return.type] the method name concatenated with somestring
def foo0
  return bar(__method__)
end
# The descriptions for foo1...
# @return [#bar@return.type] the method name concatenated with somestring
def foo1
  return bar(__method__)
end

# The descriptions for bar...
# @return [String] the method name concatenated with somestring
def bar (method)
 return method.to_s + 'somestring'
end

Ultimately what I am trying to accomplish is to document my code without having to define absolutes like a return type which are dependent on what another method is defined to be.

UPDATE: I have discovered that you are able to call # @return (see #bar) and have it list the return or the foo methods the same as bar methods but I am unable to determine how to simple get the type which is being returned and/or overload the description of the return for bar with a custom description for foo.

rudolph9
  • 8,021
  • 9
  • 50
  • 80

1 Answers1

1

As you discovered, you should use @return (see #bar) to copy the @return tag from #bar verbatim to the other docstrings. Note: it will copy the description text too. There's no way to just interpolate the type of a method. You don't seem to need it in your specific example, though.

Loren Segal
  • 3,251
  • 1
  • 28
  • 29
  • Is there a way to overload the inherited description but only use the inherited return type? – rudolph9 Apr 27 '12 at 05:26
  • Unfortunately, no. YARD only works so well at keeping things DRY. If you need to make substitutions at a really low level granularity, YARD doesn't do a very good job. That said, if your API is changing that often you should consider decoupling parts to localize the delta. – Loren Segal Apr 27 '12 at 06:30
  • I am writing an interface for a REST API which I am working toward a completely DRY implementation, [here](https://github.com/RudyIndustries/shopsense-ruby/blob/master/lib/shopsense/api.rb) is the class which is making the API calls. I'm working on defining a DSL such that all that would need to be input is the method is it's name, it's arguments (which vary in number from method to method), and their defaults. As well I would like the documentation to be DRY as well. Each of the methods have a common return type but each has a slightly different description of what they are returning. – rudolph9 Apr 27 '12 at 15:36