Merge pull request sass#2968 from mgreter/docs/data-context

Improve data context documentation

docs/api-context-example.md

@@ -1,6 +1,55 @@
-## Example main.c
+## Example for `data_context`
 
-```C
+```C:data.c
+#include <stdio.h>
+#include "sass/context.h"
+
+int main( int argc, const char* argv[] )
+{
+
+  // LibSass will take control of data you pass in
+  // Therefore we need to make a copy of static data
+  char* text = sass_copy_c_string("a{b:c;}");
+  // Normally you'll load data into a buffer from i.e. the disk.
+  // Use `sass_alloc_memory` to get a buffer to pass to LibSass
+  // then fill it with data you load from disk or somwhere else.
+
+  // create the data context and get all related structs
+  struct Sass_Data_Context* data_ctx = sass_make_data_context(text);
+  struct Sass_Context* ctx = sass_data_context_get_context(data_ctx);
+  struct Sass_Options* ctx_opt = sass_context_get_options(ctx);
+
+  // configure some options ...
+  sass_option_set_precision(ctx_opt, 10);
+
+  // context is set up, call the compile step now
+  int status = sass_compile_data_context(data_ctx);
+
+  // print the result or the error to the stdout
+  if (status == 0) puts(sass_context_get_output_string(ctx));
+  else puts(sass_context_get_error_message(ctx));
+
+  // release allocated memory
+  sass_delete_data_context(data_ctx);
+
+  // exit status
+  return status;
+
+}
+```
+
+### Compile data.c
+
+```bash
+gcc -c data.c -o data.o
+gcc -o sample data.o -lsass
+echo "foo { margin: 21px * 2; }" > foo.scss
+./sample foo.scss => "foo { margin: 42px }"
+```
+
+## Example for `file_context`
+
+```C:file.c
 #include <stdio.h>
 #include "sass/context.h"
 
@@ -34,11 +83,11 @@ int main( int argc, const char* argv[] )
 }
 ```
 
-### Compile main.c
+### Compile file.c
 
 ```bash
-gcc -c main.c -o main.o
-gcc -o sample main.o -lsass
+gcc -c file.c -o file.o
+gcc -o sample file.o -lsass
 echo "foo { margin: 21px * 2; }" > foo.scss
 ./sample foo.scss => "foo { margin: 42px }"
 ```

docs/api-doc.md

@@ -51,6 +51,10 @@ process. The compiler has two different modes: direct input as a string with
 `Sass_File_Context`. See the code for a list of options available
 [Sass_Options](https://github.com/sass/libsass/blob/36feef0/include/sass/interface.h#L18)
 
+The general rule is if the API takes const char* it will make a copy, 
+but where the API is char* it will take over memory ownership, so make sure to pass 
+in memory that is allocated via sass_copy_c_string or sass_alloc_memory.
+
 **Building a file compiler**
 
     context = sass_make_file_context("file.scss")
@@ -73,7 +77,11 @@ process. The compiler has two different modes: direct input as a string with
 
 **Building a data compiler**
 
-    context = sass_make_data_context("div { a { color: blue; } }")
+    // LibSass takes over memory owenership, make sure to allocate
+    // a buffer via `sass_alloc_memory` or `sass_copy_c_string`.
+    buffer = sass_copy_c_string("div { a { color: blue; } }")
+
+    context = sass_make_data_context(buffer)
     options = sass_data_context_get_options(context)
     sass_option_set_precision(options, 1)
     sass_option_set_source_comments(options, true)