32

I'm using YARD to document my code. I have a method that has an optional parameter with a default value. How do I notate that the parameter is optional and has a default value?

Example:

# Squares a number
# 
# @param the number to square
def square_a_number(number = 2)
  number * number
end
brainimus
  • 10,586
  • 12
  • 42
  • 64

2 Answers2

67

YARD now supports param defaults automatically.

YARD automatically figures out the default value based on the method definition. Sweedish!

For example, the following code documentation will produce the subsequent YARD doc:

Code Documentation

# Squares a number.
# 
# @param number [Integer] The number to square.
#
def square_a_number(number = 2)
  number * number
end

Resulting YARD Documentation

Parameters:
  number (Integer optional) (defaults to: 2)
David Moles
  • 48,006
  • 27
  • 136
  • 235
Joshua Pinter
  • 45,245
  • 23
  • 243
  • 245
  • 3
    Automatic inference doesn't help if you're using something like the [contracts gem](https://github.com/egonSchiele/contracts.ruby) to enforce required or optional parameters. Would be nice if YARD allowed being explicit here. – Abe Voelker Jul 26 '15 at 06:48
  • @AbeVoelker I haven't used the Contracts gem but from what I can tell, it enforces the expected **type** of the parameters, not whether they are optional or required, that is still handled by whether a value is assigned in the method parameters. – Joshua Pinter Jul 26 '15 at 15:29
  • I do use it, and [there is a `KeywordArgs` contract which allows nested `Optional` contract](https://github.com/egonSchiele/contracts.ruby/blob/8b681397c720405b1b6d355382c9ce147f2df073/TUTORIAL.md#built-in-contracts) type. Example: https://github.com/abevoelker/scrapinghub/blob/cbdb9735e6203915e0133e4896f592bfd4e5d1cd/lib/scrapinghub/jobs.rb – Abe Voelker Jul 26 '15 at 20:15
  • @AbeVoelker Ahh, I gotcha, so situations where you're defining a required method parameter of type `Hash`, like `def list(args)`, and some of the keys in `args` are required and some are optional. – Joshua Pinter Jul 26 '15 at 21:14
  • 1
    @AbeVoelker You can use `@!method` to provide a signature that includes a default in that case, and the default will be read from that just as if it were in the `def ` in the code. – Steve Jorgensen Sep 12 '15 at 01:46
-1

To mark a parameter is option you can simply use @param optional (see http://rubydoc.info/docs/yard/file/docs/Tags.md). As far as I know, there's now way to notate a default value; you're probably best to put it in the description ("the number to square, defaults to 2")

erran
  • 1,300
  • 2
  • 15
  • 36
Alex Peattie
  • 26,633
  • 5
  • 50
  • 52
  • 1
    I don't see this as an option in the documentation, and all the permutations I've tried of adding `optional` resulted in the string 'optional' being added to the output in various places without any special format. Maybe I'm missing something but this doesn't seem to be supported? – eprothro Jun 05 '14 at 20:30
  • 1
    maybe the other answer should be the accepted answer, as it does support based on the method parameter definition – msanjay Jan 30 '15 at 06:18