Incorrect documentation for authenticate_or_request_with_http_token

[collimarco]

Ruby on Rails API documentation is incorrect for authenticate_or_request_with_http_token :

# Authenticate using an HTTP Bearer token, or otherwise render an HTTP
# header requesting the client to send a Bearer token. For the authentication
# to be considered successful, +login_procedure+ should return a **non-nil**
# value. Typically, the authenticated user is returned.

The word non-nil is not the correct word to use here.

The correct word is non-falsy value, because the login procedure fails if you return nil or false.

Alternatively, the word truthy can also be used.

[zzak]

Just fyi,

https://edgeguides.rubyonrails.org/api_documentation_guidelines.html#booleans

Please avoid terms like "truthy". Ruby defines what is true and false in the language, and thus those words have a technical meaning and need no substitutes.

[collimarco]

Still the documentation is incorrect...

Based on the documentation above the method, if you return false (which is non-nil), login procedure will be considered successful.

But THAT IS NOT WHAT HAPPENS!

If you return false, the login procedure will be considered UNSUCCESSFUL.

You need to make that clear in the documentation.

NOTE: I am suggesting to fix the documentation, not the method implementation, which I think it does the correct thing.

Is now clearer?

[collimarco]

Also note that "falsy" is not the same thing as "false".

"Falsy" is a term used to indicate both "false" and "nil" at the same time.

[zzak]

Sorry, I wasn't trying to say you're wrong just that there is a precedent for not using "truthy" or "falsy" in the documentation.

If you can find a way to convey that please open a PR, I haven't looked into this beyond that yet.

[collimarco]

Personally I would use the word "non-falsy" in this context. If you say "non-false", the meaning is different...

However if you don't want to use the word "falsy"/"truthy", we can rephrase in this way:

For the authentication to be considered successful, +login_procedure+ should return a non-nil value.
If you return nil or false, then the authentication will be considered unsuccessful.

@zzak Can you please reopen the related issue so that we can fix this?

[collimarco]

@zzak As requested, I also opened the pull request here: #51927