pw_kvs: Test cleanup; comment cleanup

- Expand and cleanup comments.
- Address TODO in test. Remove some TODOs that have been addressed.
- Remove outdated, disabled tests in key_value_store_test.cc.
- Enable OffsetRead test and update it to the new Get semantics.
- Make test logging slightly less verbose.

Change-Id: I1453c6ff256be331a483e025b1e4e026dda600d7
diff --git a/pw_kvs/public/pw_kvs/flash_memory.h b/pw_kvs/public/pw_kvs/flash_memory.h
index 93ee1eb..05b823f 100644
--- a/pw_kvs/public/pw_kvs/flash_memory.h
+++ b/pw_kvs/public/pw_kvs/flash_memory.h
@@ -203,7 +203,7 @@
   //          TIMEOUT, on timeout.
   //          INVALID_ARGUMENT, if address or length is invalid.
   //          UNKNOWN, on HAL error
-  // TODO: StatusWithBool
+  // TODO: Result<bool>
   virtual Status IsRegionErased(Address source_flash_address,
                                 size_t len,
                                 bool* is_erased);
diff --git a/pw_kvs/public/pw_kvs/key_value_store.h b/pw_kvs/public/pw_kvs/key_value_store.h
index acd0955..666dd6f 100644
--- a/pw_kvs/public/pw_kvs/key_value_store.h
+++ b/pw_kvs/public/pw_kvs/key_value_store.h
@@ -78,6 +78,7 @@
   // value can be read by calling get with an offset.
   //
   //                    OK: the entry was successfully read
+  //             NOT_FOUND: the key is not present in the KVS
   //             DATA_LOSS: found the entry, but the data was corrupted
   //    RESOURCE_EXHAUSTED: the buffer could not fit the entire value, but as
   //                        many bytes as possible were written to it
@@ -120,6 +121,7 @@
   //
   Status Put(std::string_view key, span<const std::byte> value);
 
+  // Adds a key-value entry to the KVS, using an object as the value.
   template <typename T,
             typename = std::enable_if_t<std::is_trivially_copyable_v<T> &&
                                         !std::is_pointer_v<T> &&
@@ -128,8 +130,25 @@
     return Put(key, as_bytes(span(&value, 1)));
   }
 
+  // Removes a key-value entry from the KVS.
+  //
+  //                    OK: the entry was successfully added or updated
+  //             NOT_FOUND: the key is not present in the KVS
+  //             DATA_LOSS: checksum validation failed after recording the erase
+  //    RESOURCE_EXHAUSTED: insufficient space to mark the entry as deleted
+  //   FAILED_PRECONDITION: the KVS is not initialized
+  //      INVALID_ARGUMENT: key is empty or too long
+  //
   Status Delete(std::string_view key);
 
+  // Returns the size of the value corresponding to the key.
+  //
+  //                    OK: the size was returned successfully
+  //             NOT_FOUND: the key is not present in the KVS
+  //             DATA_LOSS: checksum validation failed after reading the entry
+  //   FAILED_PRECONDITION: the KVS is not initialized
+  //      INVALID_ARGUMENT: key is empty or too long
+  //
   StatusWithSize ValueSize(std::string_view key) const;
 
   void LogDebugInfo();