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.