CODEWITHSUNDEEP
rubyyard
Hommer Smith
Hommer Smith

Reputation: 27852

How to document a function that returns a specific object defined by the app in yard?

I have a function that returns a User or nil if it can't find the user. It looks like this:

  # Given an access token in the HTTP headers, it returns the User who owns the token
  #
  # @return [User] the user who owns the access token
  def set_api_user
    token = /(.*)=\"(.*)\"/.match(request.headers["Authorization"])[2]
    @api_user = ApiKey.find_by(access_token: token).user
  end

My question is, how do I document that it returns a User or nil if it can't find it?

Upvotes: 0

Views: 159

Answers (1)

Neil Slater
Neil Slater

Reputation: 27207

Ignoring the behaviour of the code for error conditions etc, in Yard, you just add the alternatives into the comment:

# @return [User,nil] the user who owns the access token

The Yard renderer will do something like this with it:

  • (User?) set_api_user

    the user who owns the access token

The little question mark is Yard's convention for "maybe you'll get this, or maybe you'll get nil"

Upvotes: 1

Related Questions