Refactor spy function documentation for clarity (#1112)

fixes #1108 (reply in thread)

Author: lovasoa

examples/official-site/sqlpage/migrations/08_functions.sql

@@ -157,8 +157,11 @@ VALUES (
         '0.7.2',
         'spy',
         '
-Hashes a password using the [Argon2](https://en.wikipedia.org/wiki/Argon2) algorithm.
-The resulting hash can be stored in the database and then used with the [authentication component](documentation.sql?component=authentication#component).
+Hashes a password with the Argon2id variant and outputs it in the [PHC string format](https://github.com/P-H-C/phc-string-format/blob/master/phc-sf-spec.md), ready to store in your users table.
+
+Every call generates a brand new cryptographic salt so that two people choosing the same password still end up with different hashes, which defeats rainbow-table attacks and lets you safely reveal only the hash.
+
+Use this function only when creating or resetting a password (for example while inserting a brand new user): it writes the stored value. Later, at login time, the [authentication component](documentation.sql?component=authentication#component) reads the stored hash, hashes the visitor''s password with the embedded salt and parameters, and grants access only if they match.
 
 ### Example