missing @return for drupal_get_token()

Tagging

Taking a look at this

I'm not sure if my explanation is entirely accurate, but I'm pretty sure it meets documentation standards if nothing else.

Since this is about docs, kicking it to Jennifer.

I am not comfortable with this documentation:
- "always the same" -- only as long as the config variables for salt and private key don't change.
- 43 characters -- that is very specific. How do you know it is always 43 characters, and is it really necessary to say that even if it is always 43 characters?

I'm not sure why it's always 43 characters, but gapple mentions it in a comment on the API doc, and I confirmed this by testing it with a bunch of different values.

Of course they are not *likely* to change, but as they're just config variables, I don't think I would word documentation to say that they *cannot* change. I think I would word it to say that as long as these configuration options aren't changed, it's unchanging, because that is always the case.

drupal_get_token() calls drupal_hmac_base64() to calculate the hash. By definition the length of a sha-256 hash has a fixed length of 256 bits (32 bytes). Base64 encoding gives a length of 44 bytes including one padding character ("=") which will get removed by the function drupal_hmac_base64().

Therefore the the length of the return value of drupal_get_token() is always 43.

Thanks... but my comments in #6 were not addressed. Also, this patch is not formatted correctly. It needs to be all one paragraph with complete sentences, with each line wrapping as close to 80 characters as possible without going over. I am also not sure that we need to document why the length is 43 characters. What we need to document is how/when the return value is the same or different.

This was my first post to an issue - let's try again ... the reason because returning fixed length token might not be interesting so let's remove this part and keep it short:

"An url safe token (fixed string of 43 chars) which will always be the same for a given $value on the same site"

See #6. "always" is not accurate -- it is only correct as long as certain settings in settings.php do not change.

Also, as far as grammar/wording: it should say "A URL-safe token..." and use "characters" not "chars", and there needs to be a comma before "which".

What's about:

"A url safe token (fixed string of 43 characters), which will always be the same for a given $value on the same site, as long as the session_id remains unchanged and $drupal_hash_salt is not modified in settings.php"

#115 is still not accurate/complete. Look at the code... How about this:

A 43-character URL-safe token for validation, based on the user session ID, the global $drupal_hash_salt variable from settings.php, and the 'drupal_private_key' configuration variable.

Sounds good. Here ya go.

I'm obviously fine with that patch. :) Any other opinions before we commit it?

Committed to 8.x and 7.x. Thanks!