Add documentation for new C-API low-level memory functions

Author: mgreter

docs/api-doc.md

@@ -16,24 +16,14 @@ This will automatically load all other headers too!
 #include "sass/context.h"
 ```
 
-### Deprecated usage
-
-The old API is kept in the source for backward compatibility.
-It's deprecated and incompatible with this documentation, use `sass/context.h`!
-
-```C
-// deprecated interface
-#include "sass/interface.h"
-```
-
 ## Basic C Example
 
 ```C
 #include <stdio.h>
 #include "sass/context.h"
 
 int main() {
-  puts(libsass_VERSION());
+  puts(libsass_version());
   return 0;
 }
 ```
@@ -114,6 +104,34 @@ This mirrors very well how `libsass` uses these structures.
 
 Structs can be down-casted to access `context` or `options`!
 
+## Memory handling and life-cycles
+
+We keep memory around for as long as the main [context](api-context.md) object is not destroyed (`sass_delete_context`). LibSass will create copies of most inputs/options beside the main sass code.
+You need to allocate and fill that buffer before passing it to LibSass. You may also overtake memory management from libsass for certain return values (i.e. `sass_context_take_output_string`).
+
+```C
+// to allocate buffer to be filled
+void* sass_alloc_memory(size_t size);
+// to allocate a buffer from existing string
+char* sass_copy_c_string(const char* str);
+// to free overtaken memory when done
+void sass_free_memory(void* ptr);
+```
+
+## Miscellaneous API functions
+
+```C
+// Some convenient string helper function
+char* sass_string_unquote (const char* str);
+char* sass_string_quote (const char* str, const char quote_mark);
+
+// Resolve a file via the given include paths in the include char* array
+char* sass_resolve_file (const char* path, const char* incs[]);
+
+// Get compiled libsass version
+const char* libsass_version(void);
+```
+
 ## Common Pitfalls
 
 **input_path**

docs/api-importer-example.md

@@ -10,10 +10,10 @@ Sass_Import_List sass_importer(const char* path, Sass_Importer_Entry cb, struct
   // get the cookie from importer descriptor
   void* cookie = sass_importer_get_cookie(cb);
   Sass_Import_List list = sass_make_import_list(2);
-  const char* local = "local { color: green; }";
-  const char* remote = "remote { color: red; }";
-  list[0] = sass_make_import_entry("/tmp/styles.scss", strdup(local), 0);
-  list[1] = sass_make_import_entry("http://www.example.com", strdup(remote), 0);
+  char* local = sass_copy_c_string("local { color: green; }");
+  char* remote = sass_copy_c_string("remote { color: red; }");
+  list[0] = sass_make_import_entry("/tmp/styles.scss", local, 0);
+  list[1] = sass_make_import_entry("http://www.example.com", remote, 0);
   return list;
 }
 
@@ -84,7 +84,7 @@ Sass_Import_List importer(const char* path, Sass_Importer_Entry cb, struct Sass_
   Sass_Import_List list = sass_make_import_list(1);
   const char* message = "some error message";
   list[0] = sass_make_import_entry(path, 0, 0);
-  sass_import_set_error(list[0], strdup(message), 0, 0);
+  sass_import_set_error(list[0], sass_copy_c_string(message), 0, 0);
   return list;
 }