doc: fix warnings from sphinx

Signed-off-by: Federico Vaga <federico.vaga@cern.ch>

drivers/fmc/fru-parse.c

@@ -8,13 +8,24 @@
 #include <linux/slab.h>
 #include <linux/ipmi/fru.h>
 
-/* The fru parser is both user and kernel capable: it needs alloc */
+/**
+ * Allocate memory
+ * @size: memory size
+ *
+ * Return: a pointer to the new allocated buffer
+ */
 void *fru_alloc(size_t size)
 {
 	return kzalloc(size, GFP_KERNEL);
 }
 
-/* Some internal helpers */
+/**
+ * Get a board info area type-length value
+ * @header: FRU header
+ * @nr: type-length number
+ *
+ * Return: a `n` type-length
+ */
 static struct fru_type_length *
 __fru_get_board_tl(struct fru_common_header *header, int nr)
 {
@@ -32,6 +43,13 @@ __fru_get_board_tl(struct fru_common_header *header, int nr)
 	return tl;
 }
 
+/**
+ * Get the string from a type-length
+ * @header: FRU header
+ * @nr: type-length number
+ *
+ * Return: a pointer to an allocated string containing the type-length value
+ */
 static char *__fru_alloc_get_tl(struct fru_common_header *header, int nr)
 {
 	struct fru_type_length *tl;
@@ -47,25 +65,48 @@ static char *__fru_alloc_get_tl(struct fru_common_header *header, int nr)
 	return fru_strcpy(res, tl);
 }
 
-/* Get various stuff, trivial */
+/**
+ * Get the manufacturer name
+ * @header: FRU header
+ *
+ * Return: a pointer to the manufacturer string (user must free the memory)
+ */
 char *fru_get_board_manufacturer(struct fru_common_header *header)
 {
 	return __fru_alloc_get_tl(header, 0);
 }
 EXPORT_SYMBOL(fru_get_board_manufacturer);
 
+/**
+ * Get the preduct name
+ * @header: FRU header
+ *
+ * Return: a pointer to the produtct string (user must free the memory)
+ */
 char *fru_get_product_name(struct fru_common_header *header)
 {
 	return __fru_alloc_get_tl(header, 1);
 }
 EXPORT_SYMBOL(fru_get_product_name);
 
+/**
+ * Get the serial number
+ * @header: FRU header
+ *
+ * Return: a pointer to the serial number string (user must free the memory)
+ */
 char *fru_get_serial_number(struct fru_common_header *header)
 {
 	return __fru_alloc_get_tl(header, 2);
 }
 EXPORT_SYMBOL(fru_get_serial_number);
 
+/**
+ * Get the part number
+ * @header: FRU header
+ *
+ * Return: a pointer to the part number string (user must free the memory)
+ */
 char *fru_get_part_number(struct fru_common_header *header)
 {
 	return __fru_alloc_get_tl(header, 3);

include/linux/fmc.h

@@ -129,7 +129,7 @@ ssize_t fmc_slot_eeprom_read(struct fmc_slot *slot,
 			     void *buf, off_t offset, size_t count);
 
 /**
- * sturct fmc_carrier_operations - FMC operations for carriers
+ * struct fmc_carrier_operations - FMC operations for carriers
  * @owner: the module that will execute the operations
  * @is_present: check if an FMC slot is present or not in the slot
  *              (present: 1, not present or error: 0). The carrier

include/uapi/linux/ipmi/fru.h

@@ -27,35 +27,62 @@ extern "C" {
  * (http://download.intel.com/design/servers/ipmi/FRU1011.pdf)
  */
 
-/* chapter 8, page 5 */
+/**
+ * struct fru_common_header - FRU header structure
+ * @format: must be 0x01
+ * @internal_use_off: for internal user - multiple of 8 bytes
+ * @chassis_info_off: chassis info - multiple of 8 bytes
+ * @board_area_off: board info area - multiple of 8 bytes
+ * @product_area_off: product area -  multiple of 8 bytes
+ * @multirecord_off: multirecord -  multiple of 8 bytes
+ * @pad: must be 0
+ * @checksum: sum modulo 256 must be 0
+ *
+ * FRU specification chapter 8, page 5
+ */
 struct fru_common_header {
-	uint8_t format;			/* 0x01 */
-	uint8_t internal_use_off;	/* multiple of 8 bytes */
-	uint8_t chassis_info_off;	/* multiple of 8 bytes */
-	uint8_t board_area_off;		/* multiple of 8 bytes */
-	uint8_t product_area_off;	/* multiple of 8 bytes */
-	uint8_t multirecord_off;	/* multiple of 8 bytes */
-	uint8_t pad;			/* must be 0 */
-	uint8_t checksum;		/* sum modulo 256 must be 0 */
+	uint8_t format;
+	uint8_t internal_use_off;
+	uint8_t chassis_info_off;
+	uint8_t board_area_off;
+	uint8_t product_area_off;
+	uint8_t multirecord_off;
+	uint8_t pad;
+	uint8_t checksum;
 };
 
 /* chapter 9, page 5 -- internal_use: not used by us */
 
 /* chapter 10, page 6 -- chassis info: not used by us */
 
-/* chapter 13, page 9 -- used by board_info_area below */
+/**
+ * struct fru_type_length
+ * @type_length: type and length
+ * @data: pointer to value
+ *
+ * FRU specification  chapter 13, page 9 -- used by board_info_area below
+ */
 struct fru_type_length {
 	uint8_t type_length;
 	uint8_t data[0];
 };
 
-/* chapter 11, page 7 */
+/**
+ * struct fru_board_info_area - Board Info Area Section
+ * @format: must be 0x01
+ * @area_len:  area length- multiple of 8 bytes
+ * @language: I hope it's 0
+ * @mfg_date: LSB, minutes since 1996-01-01
+ * @tl:	type-length stuff follows
+ *
+ * FRU specification chapter 11, page 7
+ */
 struct fru_board_info_area {
-	uint8_t format;			/* 0x01 */
-	uint8_t area_len;		/* multiple of 8 bytes */
-	uint8_t language;		/* I hope it's 0 */
-	uint8_t mfg_date[3];		/* LSB, minutes since 1996-01-01 */
-	struct fru_type_length tl[0];	/* type-length stuff follows */
+	uint8_t format;
+	uint8_t area_len;
+	uint8_t language;
+	uint8_t mfg_date[3];
+	struct fru_type_length tl[0];
 
 	/*
 	 * the TL there are in order:
@@ -71,6 +98,13 @@ struct fru_board_info_area {
 	 */
 };
 
+/**
+ * enum fru_type - List of possible FRU types
+ * @FRU_TYPE_BINARY: binary value
+ * @FRU_TYPE_BCDPLUS: BCD+ value
+ * @FRU_TYPE_ASCII6: ascii value
+ * @FRU_TYPE_ASCII: not ascii: depends on language
+ */
 enum fru_type {
 	FRU_TYPE_BINARY		= 0x00,
 	FRU_TYPE_BCDPLUS	= 0x40,
@@ -78,8 +112,11 @@ enum fru_type {
 	FRU_TYPE_ASCII		= 0xc0, /* not ascii: depends on language */
 };
 
-/*
- * some helpers
+/**
+ * Get the board info area
+ * @header: FRU header pointer
+ *
+ * Return: pointer to the board info area
  */
 static inline struct fru_board_info_area *fru_get_board_area(
 	const struct fru_common_header *header)
@@ -88,22 +125,48 @@ static inline struct fru_board_info_area *fru_get_board_area(
 	return (struct fru_board_info_area *)(header + header->board_area_off);
 }
 
+/**
+ * Get the FRU section type
+ * @tl: the type-length
+ *
+ * Return: FRU section type
+ */
 static inline int fru_type(struct fru_type_length *tl)
 {
 	return tl->type_length & 0xc0;
 }
 
+/**
+ * Get the FRU section length
+ * @tl: the type-length
+ *
+ * Return: FRU section length
+ */
 static inline int fru_length(struct fru_type_length *tl)
 {
 	return (tl->type_length & 0x3f) + 1; /* len of whole record */
 }
 
-/* assume ascii-latin1 encoding */
+/**
+ * Compute the string value lenght from type-length
+ * @tl: the type-length
+ *
+ * Return: string length
+ *
+ * assume ascii-latin1 encoding
+ */
 static inline int fru_strlen(struct fru_type_length *tl)
 {
 	return fru_length(tl) - 1;
 }
 
+/**
+ * Copy the string value from type-length
+ * @dest: destination string buffer
+ * @tl: the type-length
+ *
+ * Return: it returns the pointer to dest
+ */
 static inline char *fru_strcpy(char *dest, struct fru_type_length *tl)
 {
 	int len = fru_strlen(tl);
@@ -112,17 +175,34 @@ static inline char *fru_strcpy(char *dest, struct fru_type_length *tl)
 	return dest;
 }
 
+/**
+ * Retrieve the next type-length structure
+ * @tl: the current type-length
+ *
+ * Return: the next type-length structure
+ */
 static inline struct fru_type_length *fru_next_tl(struct fru_type_length *tl)
 {
 	return tl + fru_length(tl);
 }
 
+/**
+ * Check if there are no more type-length
+ * @tl: the current type-length
+ *
+ * Return: 1 if the current type-length is the last one
+ */
 static inline int fru_is_eof(struct fru_type_length *tl)
 {
 	return tl->type_length == 0xc1;
 }
 
-/* Public checksum verifiers */
+/**
+ * Validate FRU header checksum
+ * @header: FRU header pointer
+ *
+ * Return: 1 if the FRU header checksum is correct
+ */
 static inline int fru_header_cksum_ok(struct fru_common_header *header)
 {
 	uint8_t *ptr = (uint8_t *)header;
@@ -134,6 +214,12 @@ static inline int fru_header_cksum_ok(struct fru_common_header *header)
 	return (sum & 0xff) == 0;
 }
 
+/**
+ * Validate Board Info Area checksum
+ * @bia: board info area pointer
+ *
+ * Return: 1 if the FRU board info area checksum is correct
+ */
 static inline int fru_bia_cksum_ok(struct fru_board_info_area *bia)
 {
 	uint8_t *ptr = (uint8_t *)bia;