Update cstr_api.md

More text added

1 files changed, 24 insertions, 21 deletions

diff --git a/docs/cstr_api.md b/docs/cstr_api.md
index 4abf8a33..9ca51be1 100644
--- a/docs/cstr_api.md
+++ b/docs/cstr_api.md
@@ -1,6 +1,6 @@
 # Introduction
 
-This describes the API of **cstr_t**.
+This describes the API of string type **cstr_t**.
 
 ## Types
 
@@ -18,7 +18,7 @@ This describes the API of **cstr_t**.
 
 ## Header file
 
-All cstr definitions and prototypes may be included in your C source file by including a single header file:
+All cstr definitions and prototypes may be included in your C source file by including a single header file.
 
 ```c
 #include "stc/cstr.h"
@@ -28,22 +28,24 @@ All cstr definitions and prototypes may be included in your C source file by inc
 
 The interfaces to create a cstr_t object:
 ```c
-cstr_t        cstr_init( void );
-cstr_t        cstr_with_capacity( size_t cap );
-cstr_t        cstr_with_size( size_t len, char fill );
-cstr_t        cstr_from( const char* str );
-cstr_t        cstr_from_n( const char* str, size_t len );
-cstr_t        cstr_from_fmt( const char* fmt, ... );
+cstr_t        cstr_init( void );                           (1)
+cstr_t        cstr_with_capacity( size_t cap );            (2)
+cstr_t        cstr_with_size( size_t len, char fill );     (3)
+cstr_t        cstr_from( const char* str );                (4)
+cstr_t        cstr_from_n( const char* str, size_t len );  (5)
+cstr_t        cstr_from_fmt( const char* fmt, ... );       (6)
+cstr_t       cstr_clone( cstr_t s );                       (7)
 ```
+(1) creates an empty string, and (2) with capacity `cap`. (3) creates a cstr_t of length `len`, containing `fill` characters. (4) constructs a cstr_t from a const char* string, and (5) limits the length by `len` or strlen(str). (6) constructs a string from a formatted string `fmt` and arguments, as defined by printf(). (7) constructs a new string by cloning cstr_t `s`.
 
 ## Destruction
 ```c
 void          cstr_del( cstr_t *self );
 ```
 
-## Interface
+## cstr_t Interface
 
-### Get properties
+### Get attributes
 ```c
 size_t       cstr_size( cstr_t s );
 size_t       cstr_length( cstr_t s );
@@ -51,28 +53,29 @@ size_t       cstr_capacity( cstr_t s );
 bool         cstr_empty( cstr_t s );
 ```
 
-### Reserve, reserve, and clear string.
+### Reserve, resize and clear string
 ```c
 size_t       cstr_reserve( cstr_t* self, size_t cap );
 void         cstr_resize( cstr_t* self, size_t len, char fill );
 void         cstr_clear( cstr_t* self );
 ```
 
-### Assignment and transfer of ownership.
+### Assignment and transfer of ownership
 ```c
-cstr_t*      cstr_assign( cstr_t* self, const char* str );
-cstr_t*      cstr_assign_n( cstr_t* self, const char* str, size_t len );
-cstr_t*      cstr_take( cstr_t* self, cstr_t s );
-cstr_t       cstr_clone( cstr_t s );
-cstr_t       cstr_move( cstr_t* self );
+cstr_t*      cstr_assign( cstr_t* self, const char* str );                 (1)
+cstr_t*      cstr_assign_n( cstr_t* self, const char* str, size_t len );   (2)
+cstr_t*      cstr_take( cstr_t* self, cstr_t s );                          (3)
+cstr_t       cstr_move( cstr_t* self );                                    (4)
 ```
+(1) assigns `str` to `*self`, (2) assigns substring `str` limited by `len` or `strlen(str)`. (3) takes the constructed or moved string `s`, i.e., no allocation takes place. (4) explicitely moves `*self` to the caller of the method; `*self` becomes an empty string after move.
 
-### Append characters.
+### Append characters
 ```c
-cstr_t*      cstr_append( cstr_t* self, const char* str );
-cstr_t*      cstr_append_n( cstr_t* self, const char* str, size_t len );
-cstr_t*      cstr_push_back( cstr_t* self, char value );
+cstr_t*      cstr_append( cstr_t* self, const char* str );                (1)
+cstr_t*      cstr_append_n( cstr_t* self, const char* str, size_t len );  (2)
+cstr_t*      cstr_push_back( cstr_t* self, char ch );                     (3)
 ```
+Appends `str` (1), substring `str` limited by `len` (2), or character `ch` to `*self` (3).
 
 ### Insert characters
 ```c