better docs, note on do_stream

src/vmod_esiextra.c

@@ -55,6 +55,7 @@ vmod_bodyhash(VRT_CTX, VCL_HEADER hdr)
 	}
 
 	CAST_OBJ_NOTNULL(bo, ctx->bo, BUSYOBJ_MAGIC);
+	// XXX can leave streaming enabled with Trailer support
 	bo->do_stream = 0;
 	if (Bodyhash_push(bo->vfc, hdr->what) == NULL)
 		VRT_fail(ctx, "bodyhash push failed");

src/vmod_esiextra.vcc

@@ -12,20 +12,50 @@ $Module esiextra 3 Varnish Esiextra Module
 DESCRIPTION
 ===========
 
+This vmod contains tools to improve varnish ESI processing
+capabilities like:
+
+* generate `ETag` backend response headers
+* track the most recent `Last-Modified` date of all ESI includes.
+
+It requires chunked encoding trailer support, which, as of 2017-11-06,
+has not been merged to varnish-cache. See
+https://github.com/varnishcache/varnish-cache/pull/2477
+
 Example
     ::
 
-        import esiextra;
+	import esiextra;
+	# TODO
+
+See file `vtc/esi_recursive_full.vtc` for a full blown usage example.
 
 $Function VOID bodyhash(HEADER)
 
-Hash the received body.
+Hash the received body and write a hex-encoded string into HEADER.
+
+This function may only be called in `vcl_backend_response{}` and can
+only change `beresp.http.*` headers.
+
+If Trailer support is enabled, by setting `beresp.http.Trailer` to
+contain the name of HEADER, it will be used.
+
+Otherwise a placeholder header will be added to the cache object and
+overwritten afterwards. For this to work, it needs to disable
+streaming mode.
+
+For now, streaming mode is also disabled when Trailer support is
+enabled. This restriction may be lifted in the Future.
 
 $Object lm()
+
+Create an object to track the most reacent `Last-Modified` time during
+the entirity of an ESI request including all sub-requests.
+
 $Method BOOL .inspect(TIME)
 
-Inspect time vs. saved time. If new time is after saved time, update
-and return true. Otherwise return false.
+Inspect time vs. saved time. If new time is more recent than saved
+time, update and return true. Otherwise return false.
 
 $Method VOID .update(TIME)