Ramaze/ramaze — Issue #30: User helper user_login documentation is broken
Author: pagojo
Created: 2012-02-16 16:02:14+00:00
State: open

The user_login documentation is misleading in terms of the value returned.

The documentation in user_login for older versions such as '2010.06.18' as well as the current one state that the return value on successful login is a hash (of the supplied credentials) or nil if otherwise.

https://github.com/Ramaze/ramaze/blob/master/lib/ramaze/helper/user.rb#L119
```ruby
# shortcut for user._login but default argument are request.params
#
# @param [Hash] creds the credentials that will be passed to callback or
# model
# @return [nil Hash] the given creds are returned on successful login
#
# @api external
# @see Ramaze::Helper::User::Wrapper#_login
# @author manveru
#
def user_login(creds = request.params)
user._login(creds)
end
```
But, the older _login (e.g., in '2010.06.18') was

```ruby
# @param [Hash] creds this hash will be stored in the session on successful login
# @return [Ramaze::Helper::User::Wrapper] wrapped return value from
# model or callback
# @see Ramaze::Helper::User#user_login
# @author manveru
def _login(creds = _persistence)
if @_user = _would_login?(creds)
self._persistence = creds
end
end
```

This has changed somewhere between '2010.06.18' and '2011.07.25' to:

https://github.com/Ramaze/ramaze/blob/master/lib/ramaze/helper/user.rb#L183

```ruby
# @param [Hash] creds this hash will be stored in the session on
# successful login
# @return [Ramaze::Helper::User::Wrapper] wrapped return value from
# model or callback
# @see Ramaze::Helper::User#user_login
# @author manveru
def _login(creds = nil)
if creds
if @_user = _would_login?(creds)
Current.session.resid!
self._persistence = {:credentials => creds}
end
elsif persistence = self._persistence
@_user = _would_login?(persistence[:credentials])
end
end
```

The returned credentials are returned within another hash ``` {:credentials => creds} ``` However the documentation doesn't reflect this which is clearly misleading.