Docstrings #713

benma commented at 3:52 PM on January 16, 2020: contributor

No description provided.

benma commented at 3:53 PM on January 16, 2020: contributor

As a newcomer to the library it is a bit hard to understand what the field and scalar functions do in terms of modulo reductions. The docstrings added here would have helped me, provided they are correct :smile:

CC @sipa as per the IRC discussion today.

in src/scalar.h:38 in 305d46f921 outdated

  31 | @@ -32,7 +32,11 @@ static unsigned int secp256k1_scalar_get_bits(const secp256k1_scalar *a, unsigne
  32 |  /** Access bits from a scalar. Not constant time. */
  33 |  static unsigned int secp256k1_scalar_get_bits_var(const secp256k1_scalar *a, unsigned int offset, unsigned int count);
  34 |  
  35 | -/** Set a scalar from a big endian byte array. */
  36 | +/** Set a scalar from a big endian byte array. The scalar will be reduced modulo group order `n`.
  37 | + * In:      bin:   pointer to a 32-byte array.
  38 | + * Out:     r:     scalar to be loaded.
  39 | + *          overflow: non-zero if the scalar was larger than `n` before reduction, zero otherwise.

elichai commented at 3:55 PM on January 16, 2020:

Maybe change to "if not null is set to..."

benma commented at 4:09 PM on January 16, 2020:

fixed by adding "(can be NULL)" as seen in other docstrings.

benma force-pushed on Jan 16, 2020

elichai approved

elichai commented at 3:56 PM on January 16, 2020: contributor

I personally would really appreciate more docs in the small header files (as it doesn't even pollute code)

benma force-pushed on Jan 16, 2020

in src/scalar.h:37 in 71f8c4064c outdated

  31 | @@ -32,7 +32,11 @@ static unsigned int secp256k1_scalar_get_bits(const secp256k1_scalar *a, unsigne
  32 |  /** Access bits from a scalar. Not constant time. */
  33 |  static unsigned int secp256k1_scalar_get_bits_var(const secp256k1_scalar *a, unsigned int offset, unsigned int count);
  34 |  
  35 | -/** Set a scalar from a big endian byte array. */
  36 | +/** Set a scalar from a big endian byte array. The scalar will be reduced modulo group order `n`.
  37 | + * In:      bin:        pointer to a 32-byte array.
  38 | + * Out:     r:          scalar to be loaded.

real-or-random commented at 9:52 PM on January 16, 2020:

maybe s/loaded/set ?

benma commented at 11:42 AM on January 17, 2020:

:heavy_check_mark:

scalar: extend docstring of secp256k1_scalar_set_b32 dc7d8fd9e2

field: extend docstring of secp256k1_fe_normalize dabfea7e21

benma force-pushed on Jan 17, 2020

real-or-random commented at 1:15 PM on January 17, 2020: contributor

ACK dabfea7e217b129d10f0f787722626f388dddb5a

jonasnick approved

jonasnick commented at 12:33 PM on January 24, 2020: contributor

ACK dabfea7

jonasnick referenced this in commit 1b4d256e2e on Jan 24, 2020

jonasnick merged this on Jan 24, 2020

jonasnick closed this on Jan 24, 2020

sipa cross-referenced this on Jun 9, 2020 from issue Update libsecp256k1 subtree by sipa

fanquake referenced this in commit 8c97780db8 on Jun 13, 2020

sidhujag referenced this in commit 8a3a072968 on Jun 13, 2020

ComputerCraftr referenced this in commit b98f1c6e6c on Jun 16, 2020

UdjinM6 referenced this in commit 9d36ba6570 on Aug 10, 2021

5tefan referenced this in commit 8ded2caa74 on Aug 12, 2021

gades referenced this in commit d855cc511d on May 8, 2022