subsys/fs/nvs: nvs_write return missing documentation

- Documentation of the 0 return value for ns_write function
- Ajusted lines length limit from 80 to 100
- Fixed extra and missing parameters for nvs_fs
- Misc spelling/grammar changes

Signed-off-by: Ramiro Merello <rmerello@itba.edu.ar>

include/fs/nvs.h

@@ -34,26 +34,23 @@ extern "C" {
  * @brief Non-volatile Storage File system structure
  *
  * @param offset File system offset in flash
- * @param ate_wra: Allocation table entry write address. Addresses are stored
+ * @param ate_wra Allocation table entry write address. Addresses are stored as uint32_t:
- * as uint32_t: high 2 bytes are sector, low 2 bytes are offset in sector,
+ * high 2 bytes correspond to the sector, low 2 bytes are the offset in the sector
- * @param data_wra: Data write address.
+ * @param data_wra Data write address
- * @param sector_size File system is divided into sectors each sector should be
+ * @param sector_size File system is split into sectors, each sector must be multiple of pagesize
- * multiple of pagesize
+ * @param sector_count Number of sectors in the file systems
- * @param sector_count Amount of sectors in the file systems
+ * @param ready Flag indicating if the filesystem is initialized
- * @param write_block_size Alignment size
  * @param nvs_lock Mutex
- * @param flash_device Flash Device
+ * @param flash_device Flash Device runtime structure
+ * @param flash_parameters Flash memory parameters structure
  */
 struct nvs_fs {
-	off_t offset;		/* filesystem offset in flash */
+	off_t offset;
-	uint32_t ate_wra;		/* next alloc table entry write address */
+	uint32_t ate_wra;
-	uint32_t data_wra;		/* next data write address */
+	uint32_t data_wra;
-	uint16_t sector_size;	/* filesystem is divided into sectors,
+	uint16_t sector_size;
-				 * sector size should be multiple of pagesize
+	uint16_t sector_count;
-				 */
+	bool ready;
-	uint16_t sector_count;	/* amount of sectors in the filesystem */
-	bool ready;		/* is the filesystem initialized ? */
-
 	struct k_mutex nvs_lock;
 	const struct device *flash_device;
 	const struct flash_parameters *flash_parameters;
@@ -102,10 +99,10 @@ int nvs_clear(struct nvs_fs *fs);
  * @param data Pointer to the data to be written
  * @param len Number of bytes to be written
  *
- * @return Number of bytes written. On success, it will be equal to the number
+ * @return Number of bytes written. On success, it will be equal to the number of bytes requested
- * of bytes requested to be written. On error returns -ERRNO code.
+ * to be written. When a rewrite of the same data already stored is attempted, nothing is written
+ * to flash, thus 0 is returned. On error, returns negative value of errno.h defined error codes.
  */
-
 ssize_t nvs_write(struct nvs_fs *fs, uint16_t id, const void *data, size_t len);
 
 /**
@@ -130,10 +127,10 @@ int nvs_delete(struct nvs_fs *fs, uint16_t id);
  * @param data Pointer to data buffer
  * @param len Number of bytes to be read
  *
- * @return Number of bytes read. On success, it will be equal to the number
+ * @return Number of bytes read. On success, it will be equal to the number of bytes requested
- * of bytes requested to be read. When the return value is larger than the
+ * to be read. When the return value is larger than the number of bytes requested to read this
- * number of bytes requested to read this indicates not all bytes were read,
+ * indicates not all bytes were read, and more data is available. On error, returns negative
- * and more data is available. On error returns -ERRNO code.
+ * value of errno.h defined error codes.
  */
 ssize_t nvs_read(struct nvs_fs *fs, uint16_t id, void *data, size_t len);
 
@@ -146,15 +143,14 @@ ssize_t nvs_read(struct nvs_fs *fs, uint16_t id, void *data, size_t len);
  * @param id Id of the entry to be read
  * @param data Pointer to data buffer
  * @param len Number of bytes to be read
- * @param cnt History counter: 0: latest entry, 1:one before latest ...
+ * @param cnt History counter: 0: latest entry, 1: one before latest ...
  *
- * @return Number of bytes read. On success, it will be equal to the number
+ * @return Number of bytes read. On success, it will be equal to the number of bytes requested
- * of bytes requested to be read. When the return value is larger than the
+ * to be read. When the return value is larger than the number of bytes requested to read this
- * number of bytes requested to read this indicates not all bytes were read,
+ * indicates not all bytes were read, and more data is available. On error, returns negative
- * and more data is available. On error returns -ERRNO code.
+ * value of errno.h defined error codes.
  */
-ssize_t nvs_read_hist(struct nvs_fs *fs, uint16_t id, void *data, size_t len,
+ssize_t nvs_read_hist(struct nvs_fs *fs, uint16_t id, void *data, size_t len, uint16_t cnt);
-		  uint16_t cnt);
 
 /**
  * @brief nvs_calc_free_space
@@ -163,10 +159,9 @@ ssize_t nvs_read_hist(struct nvs_fs *fs, uint16_t id, void *data, size_t len,
  *
  * @param fs Pointer to file system
  *
- * @return Number of bytes free. On success, it will be equal to the number
+ * @return Number of bytes free. On success, it will be equal to the number of bytes that can
- * of bytes that can still be written to the file system. Calculating the
+ * still be written to the file system. Calculating the free space is a time consuming operation,
- * free space is a time consuming operation, especially on spi flash.
+ * especially on spi flash. On error, returns negative value of errno.h defined error codes.
- * On error returns -ERRNO code.
  */
 ssize_t nvs_calc_free_space(struct nvs_fs *fs);