Merge bitcoin#713: Docstrings

dabfea7 field: extend docstring of secp256k1_fe_normalize (Marko Bencun)
dc7d8fd scalar: extend docstring of secp256k1_scalar_set_b32 (Marko Bencun)

Pull request description:

ACKs for top commit:
  real-or-random:
    ACK dabfea7
  jonasnick:
    ACK dabfea7

Tree-SHA512: aeed17dad281296e46d94007c864ba07f41a347525b049385a0a71640de84c3094bcc51d2fb4132b2a8f575acfe8ae53d7e28790bf328cac1892d040a9c50f70

src/field.h

@@ -32,10 +32,12 @@
 
 #include "util.h"
 
-/** Normalize a field element. */
+/** Normalize a field element. This brings the field element to a canonical representation, reduces
+ *  its magnitude to 1, and reduces it modulo field size `p`.
+ */
 static void secp256k1_fe_normalize(secp256k1_fe *r);
 
-/** Weakly normalize a field element: reduce it magnitude to 1, but don't fully normalize. */
+/** Weakly normalize a field element: reduce its magnitude to 1, but don't fully normalize. */
 static void secp256k1_fe_normalize_weak(secp256k1_fe *r);
 
 /** Normalize a field element, without constant-time guarantee. */

src/scalar.h

@@ -32,7 +32,11 @@ static unsigned int secp256k1_scalar_get_bits(const secp256k1_scalar *a, unsigne
 /** Access bits from a scalar. Not constant time. */
 static unsigned int secp256k1_scalar_get_bits_var(const secp256k1_scalar *a, unsigned int offset, unsigned int count);
 
-/** Set a scalar from a big endian byte array. */
+/** Set a scalar from a big endian byte array. The scalar will be reduced modulo group order `n`.
+ * In:      bin:        pointer to a 32-byte array.
+ * Out:     r:          scalar to be set.
+ *          overflow:   non-zero if the scalar was bigger or equal to `n` before reduction, zero otherwise (can be NULL).
+ */
 static void secp256k1_scalar_set_b32(secp256k1_scalar *r, const unsigned char *bin, int *overflow);
 
 /** Set a scalar to an unsigned integer. */