Add comments advising to close a digester or `Digesting{Reader,Writer…

…}` before

calling `Digest()` (there was a comment at `Close()` for a digester but not at
`Digest()`).

Add comments that calling `Digest()` and then accepting more data or calling
`Digest()` again is not guaranteed to be supported.

PiperOrigin-RevId: 683632672

riegeli/digests/digester_handle.h

@@ -475,6 +475,12 @@ struct IsValidDigesterTarget<
 //   //
 //   // `OriginalDigestType` can be any type convertible to `DigestType` using
 //   // `DigestConverter`.
+//   //
+//   // Depending on the digester, `Digest()` can be more efficient if `Close()`
+//   // is called before.
+//   //
+//   // Many digesters support calling `Digest()` and then accepting more data
+//   // or calling `Digest()` again, but this is not guaranteed.
 //   OriginalDigestType Digest();
 // ```
 //

riegeli/digests/digesting_reader.h

@@ -146,6 +146,12 @@ class DigestingReader : public DigestingReaderBase {
   // Digests buffered data if needed, and returns the digest.
   //
   // The digest is converted to `DesiredDigestType` using `DigestConverter`.
+  //
+  // Depending on the digester, `Digest()` can be more efficient if `Close()` is
+  // called before.
+  //
+  // Many digesters support calling `Digest()` and then accepting more data or
+  // calling `Digest()` again, but this is not guaranteed.
   template <
       typename DesiredDigestType = DigestType,
       std::enable_if_t<HasDigestConverter<DigestType, DesiredDigestType>::value,

riegeli/digests/digesting_writer.h

@@ -180,6 +180,12 @@ class DigestingWriter : public DigestingWriterBase {
   // Digests buffered data if needed, and returns the digest.
   //
   // The digest is converted to `DesiredDigestType` using `DigestConverter`.
+  //
+  // Depending on the digester, `Digest()` can be more efficient if `Close()` is
+  // called before.
+  //
+  // Many digesters support calling `Digest()` and then accepting more data or
+  // calling `Digest()` again, but this is not guaranteed.
   template <
       typename DesiredDigestType = DigestType,
       std::enable_if_t<HasDigestConverter<DigestType, DesiredDigestType>::value,