Add more hello-wuffs-c commentary

hello-wuffs-c/README.md

@@ -20,7 +20,7 @@ pointer. Anyway, here's what the output should look like:
 
 ```
 $ ./run.sh
---- C Implementation prints ---
+--- C Implementation Prints ---
 0
 12
 56789

hello-wuffs-c/main.c

@@ -12,14 +12,12 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-// ----------------
-
 #include <inttypes.h>
 #include <stdio.h>
 #include <string.h>
 
-// See naive-parse.c and wuffs-parse.c for implementations of this function
-uint32_t parse(char *, size_t);
+// See naive-parse.c and wuffs-parse.c for implementations of this function.
+uint32_t parse(char*, size_t);
 
 void run(char* p) {
   size_t n = strlen(p) + 1;  // +1 for the trailing NUL that ends a C string.

hello-wuffs-c/naive-parse.c

@@ -1,5 +1,19 @@
-#include <stdlib.h>
+// Copyright 2019 The Wuffs Authors.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//    https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 #include <inttypes.h>
+#include <stdlib.h>
 
 uint32_t parse(char* p, size_t n) {
   uint32_t ret = 0;

hello-wuffs-c/run.sh

@@ -22,10 +22,10 @@ CC=${CC:-gcc}
 # beforehand, to install the wuffs-c compiler.
 wuffs-c gen -package_name demo < parse.wuffs > parse.c
 
-echo --- C Implementation prints ---
-$CC main.c naive-parse.c
-./a.out
+echo --- C Implementation Prints ---
+$CC main.c naive-parse.c -o n.out
+./n.out
 
 echo ------ Wuffs Impl Prints ------
-$CC main.c wuffs-parse.c
-./a.out
+$CC main.c wuffs-parse.c -o w.out
+./w.out

hello-wuffs-c/wuffs-parse.c

@@ -1,3 +1,17 @@
+// Copyright 2019 The Wuffs Authors.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//    https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 #include <stdio.h>
 
 // TODO: this 'rough edge' shouldn't be necessary. See
@@ -9,33 +23,65 @@
 
 uint32_t parse(char* p, size_t n) {
   wuffs_base__status status;
-  // If you want this on the heap instead, use
-  // wuffs_demo__parser *parser = wuffs_demo__parser__alloc();
-  // and don't run __initialize();
+
+  // This next line of code allocates a wuffs_demo__parser on the stack. Stack
+  // allocation in C means uninitialized memory, so we need to call
+  // wuffs_demo__parser__initialize afterwards.
+  //
+  // An alternative, allocating on the heap and initializing in a single
+  // function call, is to say:
+  //
+  //  wuffs_demo__parser* parser = wuffs_demo__parser__alloc();
+  //  if (!parser) {
+  //    // Out of memory.
+  //    return 0;
+  //  }
+  //  // No need to call wuffs_demo__parser__initialize, but don't forget to
+  //  // free(parser) before this function returns, taking extra care if this
+  //  // function has multiple return points. Wuffs has no destructor functions
+  //  // and Wuffs types never hold or own any resources in the RAII sense.
+  //  // Just free the memory.
+  //
+  // For stack allocation, the C compiler needs to know
+  // sizeof(wuffs_demo__parser), but that compile-time value isn't guaranteed
+  // to be stable across Wuffs versions. Stack allocation is therefore only
+  // valid when the C file also #define's WUFFS_IMPLEMENTATION. When linking
+  // against a separately built Wuffs library (and the Wuffs types in this
+  // compilation are incomplete types), you'll have to use heap allocation.
   wuffs_demo__parser parser;
+
+  // Initialize (and check status). An error here means that bad arguments were
+  // passed to wuffs_demo__parser__initialize.
+  //
+  // There are two other categories of not-OK status values, notes and
+  // suspensions, but they won't be encountered in this example.
   status = wuffs_demo__parser__initialize(&parser, sizeof__wuffs_demo__parser(),
                                           WUFFS_VERSION, 0);
-  // This happens when bad arguments are passed to __initialize()
   if (!wuffs_base__status__is_ok(&status)) {
     printf("initialize: %s\n", wuffs_base__status__message(&status));
     return 0;
   }
 
-  wuffs_base__io_buffer iobuf;
-  iobuf.data.ptr = (uint8_t*)p;
-  iobuf.data.len = n;
-  iobuf.meta.wi = n;
-  iobuf.meta.ri = 0;
-  iobuf.meta.pos = 0;
-  iobuf.meta.closed = true;
+  // True means that the wuffs_base__io_buffer is closed - we are at the end of
+  // the input. False would mean that there might be additional data in the
+  // byte stream (that this buffer is not large enough to hold all at once).
+  //
+  // In general, Wuffs' coroutine and suspension status mechanisms let it parse
+  // arbitrarily large data streams using fixed sized buffers, but that won't
+  // be encountered in this example.
+  wuffs_base__io_buffer iobuf =
+      wuffs_base__ptr_u8__reader((uint8_t*)p, n, true);
 
-  // This happens when wuffs code returns "# Some status"
+  // Parse (and check status). An error here means that we had invalid input
+  // (i.e. "#not a digit" or "#too large").
+  //
+  // There are two other categories of not-OK status values, notes and
+  // suspensions, but they won't be encountered in this example.
   status = wuffs_demo__parser__parse(&parser, &iobuf);
   if (!wuffs_base__status__is_ok(&status)) {
     printf("parse: %s\n", wuffs_base__status__message(&status));
     return 0;
   }
 
-  uint32_t ret = wuffs_demo__parser__value(&parser);
-  return ret;
+  return wuffs_demo__parser__value(&parser);
 }