More complete examples of ETag/I-N-M for .id() and .sha256().

README.rst

@@ -488,13 +488,33 @@ BLOB xreader.id()
 
 Returns a unique, opaque identifier for the state of the file as
 determined when it was most recently checked. The ID changes if and
-only if the file was found to have changed.
+only if the file was found to have changed. Invokes VCL failure if the
+most recent update check encountered an error.
 
 Example::
 
+  # Use the base64 encoding of .id() for the ETag response header, and
+  # send a 304 response if the If-None-Match request header matches
+  # it.
+
   import blob;
 
-  set resp.http.ETag = blob.encode(BASE64, blob=rdr.id());
+  sub vcl_recv {
+     if (req.http.If-None-Match == blob.encode(BASE64, blob=rdr.id())) {
+	return (synth(304));
+     }
+     else {
+	return (synth(200));
+     }
+  }
+
+  sub vcl_synth {
+      set resp.http.ETag = blob.encode(BASE64, blob=rdr.id());
+      if (resp.status == 200) {
+	rdr.synth();
+      }
+      return(deliver);
+  }
 
 The contents of the BLOB returned by ``.id()`` are intentionally not
 documented, and should not be relied on to extract information about
@@ -514,6 +534,9 @@ check encountered an error.
 
 Example::
 
+  # Use .sha256() for the ETag and If-None-Match headers, as shown
+  # above for .id().
+
   import blob;
 
   sub vcl_init {
@@ -534,6 +557,7 @@ Example::
       if (resp.status == 200) {
 	rdr.synth();
       }
+      return(deliver);
   }
 
 The ``.sha256()`` and ``.id()`` methods both return a digest for the

src/vmod_file.vcc

@@ -444,13 +444,33 @@ $Method BLOB .id()
 
 Returns a unique, opaque identifier for the state of the file as
 determined when it was most recently checked. The ID changes if and
-only if the file was found to have changed.
+only if the file was found to have changed. Invokes VCL failure if the
+most recent update check encountered an error.
 
 Example::
 
+  # Use the base64 encoding of .id() for the ETag response header, and
+  # send a 304 response if the If-None-Match request header matches
+  # it.
+
   import blob;
 
-  set resp.http.ETag = blob.encode(BASE64, blob=rdr.id());
+  sub vcl_recv {
+     if (req.http.If-None-Match == blob.encode(BASE64, blob=rdr.id())) {
+	return (synth(304));
+     }
+     else {
+	return (synth(200));
+     }
+  }
+
+  sub vcl_synth {
+      set resp.http.ETag = blob.encode(BASE64, blob=rdr.id());
+      if (resp.status == 200) {
+	rdr.synth();
+      }
+      return(deliver);
+  }
 
 The contents of the BLOB returned by ``.id()`` are intentionally not
 documented, and should not be relied on to extract information about
@@ -467,6 +487,9 @@ check encountered an error.
 
 Example::
 
+  # Use .sha256() for the ETag and If-None-Match headers, as shown
+  # above for .id().
+
   import blob;
 
   sub vcl_init {
@@ -487,6 +510,7 @@ Example::
       if (resp.status == 200) {
 	rdr.synth();
       }
+      return(deliver);
   }
 
 The ``.sha256()`` and ``.id()`` methods both return a digest for the