field: correct `_fe_half` docs (output is not normalized, input requires magnitude <= 31) #1878

After reviewing #1877, I took a look at the other field module function docs w.r.t. their normalized/magnitude promises and found this mismatch: the secp256k1_fe_half docs state the output is normalized, but the impl sets r->normalized = 0 (it only halves the limbs, without a reduction):

https://github.com/bitcoin-core/secp256k1/blob/bd0287d650c24dc41e0362675a9f6a49ee952def/src/field_impl.h#L448-L450

This is a minimum-diff fix to match the implementation, with a similar "On output" structure as used for _fe_add: https://github.com/bitcoin-core/secp256k1/blob/bd0287d650c24dc41e0362675a9f6a49ee952def/src/field.h#L246

utACK 56707cc0b8aea884c7bc55e9973cd3b4b676976f

I took a look at the other field module function docs w.r.t. their normalized/magnitude promises

Thanks! How confident are you that this is the only one (beyond #1877)?

I took a look at the other field module function docs w.r.t. their normalized/magnitude promises

Thanks! How confident are you that this is the only one (beyond #1877)?

I was almost about to reply "quite confident", but then found another one even within fe_half: for the input r the implementation checks for magnitude <= 31, which is not documented as requirement:

https://github.com/bitcoin-core/secp256k1/blob/bd0287d650c24dc41e0362675a9f6a49ee952def/src/field.h#L326 https://github.com/bitcoin-core/secp256k1/blob/bd0287d650c24dc41e0362675a9f6a49ee952def/src/field_impl.h#L444-L446

In this case it's less clear for me on whether the documentation or the implementation needs to be adapted. (When in doubt, keeping the more conservative choice of 31 seems fine though, as I don't think we are close to that magnitude anytime soon, or probably ever; on the other hand it's just noise if it's not really needed).

// EDIT: Decided to keep the current bound and updated the docs to be on the safe side.

In this case it's less clear for me on whether the documentation or the implementation needs to be adapted.

The check is meaningful: https://github.com/bitcoin-core/secp256k1/blob/86c7cbaf5af0c7a15c40e1c825ea0ee0c0146175/src/field_10x26_impl.h#L1041

Within that function, in the 10x26 implementation, the limbs reach values with magnitude "m+1/2" effectively, and this would overflow limbs t0..t8 due to 0x3FFFFFF * 2 * (32+1/2) = 0x4362076095 > UINT32_MAX.

So updating the docs is the correct choice here.

ACK 56e031a14828a3b0e9a0b3d3626ca48e76716d98