py: Add comments for vstr_init and mp_obj_new_str.

2 files changed, 9 insertions, 0 deletions

diff --git a/py/objstr.c b/py/objstr.c
index f25ec17378..f7cb43560f 100644
--- a/py/objstr.c
+++ b/py/objstr.c
@@ -1856,6 +1856,8 @@ const mp_obj_type_t mp_type_bytes = {
 // the zero-length bytes
 const mp_obj_str_t mp_const_empty_bytes_obj = {{&mp_type_bytes}, 0, 0, NULL};
 
+// Create a str/bytes object using the given data.  New memory is allocated and
+// the data is copied across.
 mp_obj_t mp_obj_new_str_of_type(const mp_obj_type_t *type, const byte* data, mp_uint_t len) {
     mp_obj_str_t *o = m_new_obj(mp_obj_str_t);
     o->base.type = type;
@@ -1870,6 +1872,9 @@ mp_obj_t mp_obj_new_str_of_type(const mp_obj_type_t *type, const byte* data, mp_
     return o;
 }
 
+// Create a str/bytes object from the given vstr.  The vstr buffer is resized to
+// the exact length required and then reused for the str/bytes object.  The vstr
+// is cleared and can safely be passed to vstr_free if it was heap allocated.
 mp_obj_t mp_obj_new_str_from_vstr(const mp_obj_type_t *type, vstr_t *vstr) {
     // if not a bytes object, look if a qstr with this data already exists
     if (type == &mp_type_str) {
diff --git a/py/vstr.c b/py/vstr.c
index 63358d5957..e71a6b7bc1 100644
--- a/py/vstr.c
+++ b/py/vstr.c
@@ -35,6 +35,8 @@
 // returned value is always at least 1 greater than argument
 #define ROUND_ALLOC(a) (((a) & ((~0) - 7)) + 8)
 
+// Init the vstr so it allocs exactly given number of bytes.
+// Length is set to zero, and null byte written in first position.
 void vstr_init(vstr_t *vstr, size_t alloc) {
     if (alloc < 2) {
         // need at least 1 byte for the null byte at the end
@@ -52,6 +54,8 @@ void vstr_init(vstr_t *vstr, size_t alloc) {
     vstr->fixed_buf = false;
 }
 
+// Init the vstr so it allocs exactly enough ram to hold given length (plus the
+// null terminating byte), set the length, and write the null byte at the end.
 void vstr_init_len(vstr_t *vstr, size_t len) {
     vstr_init(vstr, len + 1);
     vstr_add_len(vstr, len);