[Skiboot] [PATCH 1/2] flash: Add documentation for blocklevel_smart_write()

[Michael Neuling]

A function called "smart" doesn't give the user any clues as to why
they would want to use it over a another calls.

This adds some documentation so users can determine when to best use
this call.

Signed-off-by: Michael Neuling <mikey at neuling.org>
---
 libflash/blocklevel.h | 9 ++++++++-
 1 file changed, 8 insertions(+), 1 deletion(-)

diff --git a/libflash/blocklevel.h b/libflash/blocklevel.h
index 9f4285e..9770e11 100644
--- a/libflash/blocklevel.h
+++ b/libflash/blocklevel.h
@@ -64,7 +64,14 @@ int blocklevel_erase(struct blocklevel_device *bl, uint32_t pos, uint32_t len);
 int blocklevel_get_info(struct blocklevel_device *bl, const char **name, uint32_t *total_size,
 		uint32_t *erase_granule);
 
-/* Convienience functions */
+/*
+ * blocklevel_smart_write() performs reads on the data to see if it
+ * can skip erase or write calls. This is likely more conveient for
+ * the caller since they don't need to perform these checks
+ * themselves. Depending on the new and old data, this may be faster
+ * or slower than the just using blocklevel_erase/write calls.
+ * directly.
+ */
 int blocklevel_smart_write(struct blocklevel_device *bl, uint32_t pos, const void *buf, uint32_t len);
 
 /* Implemented in software at this level */
-- 
2.7.4