Dynamic documentation, using the return of method in the description of another YARD?

问题

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.

回答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.

来源：https://stackoverflow.com/questions/10321789/dynamic-documentation-using-the-return-of-method-in-the-description-of-another

标签

ruby

documentation

yard