Improving code comments: Document length of buffer arguments
hannob opened this issue · 1 comments
hannob commented
It would be very helpful to document which constants describe the lengths of the input/output buffers.
As an example here's the code comment for the function indcpa_enc:
/*************************************************
* Name: indcpa_enc
*
* Description: Encryption function of the CPA-secure
* public-key encryption scheme underlying Kyber.
*
* Arguments: - unsigned char *c: pointer to output ciphertext
* - const unsigned char *m: pointer to input message (of length KYBER_SYMBYTES bytes)
* - const unsigned char *pk: pointer to input public key
* - const unsigned char *coin: pointer to input random coins used as seed
* to deterministically generate all randomness
**************************************************/
All 4 parameters have a fixed size, however only for m it's documented. Without being familiar with the internals of kyber it's hard to figure out what size c, pk and coin should have. I'd therefore recommend to document in all cases of input buffers which constant from params.h describes their length.
gregorseiler commented
Pointers to constant-length arrays in function arguments are written as arrays with specified length now.