Add docs to Crypto::Bcrypt

[j8r]

This method is untested, and is a little variation of the "standard" Crypto::Bcrypt.new constructor.

There are also other points I think can be improved in Crypto::Bcrypt, I have kept this PR minimal.

Only adding docs on this PR.

[straight-shoota]

I'm not sure about this. hash_secret seems like a nice convenience method if you just want a simple string hash with no seed.
The seed is not optional for Crypto::Bcrypt.new, though. It's a more advanced interface and IMO it makes sense to force users to think about it. Also it's probably not a good idea to mix constructor arguments accepting String and Byte for password and salt.

[j8r]

@straight-shoota For a more advanced wrapper, there is Crypto::Bcrypt::Password (which could IMO be included in Crypto::Bcrypt by the way).

[j8r]

I think it is great for the user to know what is the default salt value in the API docs. I can split to two overload though, one for Bytes and the other for String.

[j8r]

An other option is to merge Crypto::Bcrypt::Password into Crypto::Bcrypt. Do we want this change now?

[straight-shoota]

I actually don't see any benefit from this.

hash_secret is a convenience method based on Bcrypt for simple uses. Being a separate method you can't accidentally "forget" to pass a salt when initializing an instance with Bcrypt.new because the compiler enforces it.
If we go with this patch, all usages of Bcrypt.hash_secret would need to be replaced by Bcrypt.new.to_s. And the entire API would be more susceptible to mistakes because you could always omit the salt.

The method not being tested can be fixed by adding a test. The added documentation is also great. But I wouldn't change the API because it's exactly like it should be.

[straight-shoota]

Regarding Bcrypt::Password, please create a new issue.

[j8r]

I don't agree @straight-shoota , because one could use .new instead of .hash_secret, by mistake (or not). It is not obvious which one is "safer" than the other.

[j8r]

Anyway, ok. I'll do the non-controversial changes here, first, and open an issue for broader API improvements about the Bcrypt class.

[straight-shoota]

When calling Bcrypt.new, salt is a required argument. You can't just miss it by mistake.

[j8r]

I didn't add a test, because hash_secret will require Crypto::Bcrypt::Password to check the values.

[straight-shoota]

That's probably fine. It's tested indirectly through the specs for Password.create.

[j8r]

These are now just docs, can we move forward please?

[j8r]

Anything blocking the PR?