How do I prevent Yard from using the contents of @return as description?

Question

I have nothing useful to write about this function other than specifying what it outputs. If Yard doesn't find a description, it uses the contents of @return instead. Is there any way to prevent that? I want to avoid silly duplication like you see in the example below.

##
# @return [Array<Hash>]
#
#   an array of hashes. Example output:
#
#     [
#       {:name=>"FORNEBU", :municipality=>"BÆRUM", :county=>"AKERSHUS"},
#       {:name=>"FORSAND", :municipality=>"FORSAND", :county=>"ROGALAND"}
#     ]
#

Screenshot

The image link is broken. Presumably the array of hashes has some kind of purpose or meaning, why not document that? If you *really* have nothing to say about a method, then is there any purpose to documenting it at all? Although this is not code review (hence this is not an answer), I cannot tell what your method does from your documentation, so perhaps there *is* something missing? — Neil Slater, Apr 30 '14 at 18:47
@NeilSlater: The image link is not broken... http://i.stack.imgur.com/nJevf.png — Hubro, May 02 '14 at 02:57
Agreed, the link is now working. It was not working when I commented. I assume you are not documenting the params to make repetition in the example clearer? I'd say `search_cities` is reasonably intuitive method name, but I still don't buy "I have nothing useful to write about this function" - even if you simply clarified the scope of the search in four or five word summary, it would solve your problem *and* make the documentation better. And you *already* have tautology in `[Array] an array of hashes.` — Neil Slater, May 02 '14 at 07:11

score 1 · Answer 1 · answered Apr 28 '18 at 17:09

you can use @example tag

##
# @return [Array<Hash>]
# @example
#   an array of hashes. Example output:
#
#     [
#       {:name=>"FORNEBU", :municipality=>"BÆRUM", :county=>"AKERSHUS"},
#       {:name=>"FORSAND", :municipality=>"FORSAND", :county=>"ROGALAND"}
#     ]
#

output

and the method description will be like this:

#method_name(args) ⇒ Array<Hash>

How do I prevent Yard from using the contents of @return as description?

1 Answers1