docs: comments for blob, stuffer methods #5326
Conversation
| `s2n_blob` is a very simple data structure: | ||
| `s2n_blob` is a data structure representing allocated, "owned" memory or a reference to some other slice of memory. |
There was a problem hiding this comment.
I know you later say "or a reference to some other slice of memory", but I worry that someone is still still going to read this as "blobs are always allocated". Maybe just "s2n_blob is a data structure representing a slice of memory"?
| /** | ||
| * Initialize a stuffer to reference some mutable data `in`. |
There was a problem hiding this comment.
I know the function signature specifies that the data is mutable, but often we just assume it's not because there's no immutable version 😬 I wonder if you should remove the "mutable".
Same for blob down below.
| * Resize a blob to `size`. The blob must be allocated or empty. | ||
| * |
There was a problem hiding this comment.
Did you mean "growable"?
| * Resize a blob to `size`. The blob must be allocated or empty. | |
| * | |
| * Resize a blob to `size`. The blob must be growable or empty. | |
| * |
| * Copy the data in `from` to a new allocated blob. | ||
| */ |
There was a problem hiding this comment.
This one always trips me up. I wonder if we should be even more specific about the fact that to will be allocated as part of this operation. "Allocate enough memory for to to contain all the data in from, then copy the data in from to to."
Description of changes:
Add comments for some stuffer and blob methods.
I have reread the implementations of a lot of stuffer/blob methods many times because I keep forgetting what they do, and can't tell from the name.
I acknowledge that most of the methods are small so reading them shouldn't be a big deal, but having to jump in and out of the files when I am reviewing PR's is not fun. By adding comments, my IDE will just tell me what the functions do when I mouse over them.
By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.