libflashrom: Move documentation to header

The doxygen documentation was in the libflashrom.c file. Move the
documentation to the libflashrom.h file. This allows foreign function
interface binding generators (eg rust bindgen) that operate on the .h
file to generate documentation for the target language. Some doxygen
errors were also corrected, mostly undocumented or wrongly labeled
parameters.

To test, I have diffed and inspected the doxygen documentation before
and after the change. All functions are documented the same, and the
structs and enums are now also included in the docs.

Change-Id: I856b74d5bfea13722539be15496755a95e701eea
Signed-off-by: Evan Benn <evanbenn@chromium.org>
Reviewed-on: https://review.coreboot.org/c/flashrom/+/63903
Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
Reviewed-by: Angel Pons <th3fanbus@gmail.com>
Reviewed-by: Edward O'Callaghan <quasisec@chromium.org>
Reviewed-by: Felix Singer <felixsinger@posteo.net>

1 files changed, 0 insertions, 51 deletions

diff --git a/layout.c b/layout.c
index 05bee19c..39f504ac 100644
--- a/layout.c
+++ b/layout.c
@@ -351,19 +351,6 @@ const struct romentry *layout_next(
 	return iterator ? iterator->next : layout->head;
 }
 
-/**
- * @addtogroup flashrom-layout
- * @{
- */
-
-/**
- * @brief Create a new, empty layout.
- *
- * @param layout Pointer to returned layout reference.
- *
- * @return 0 on success,
- *         1 if out of memory.
- */
 int flashrom_layout_new(struct flashrom_layout **const layout)
 {
 	*layout = malloc(sizeof(**layout));
@@ -377,17 +364,6 @@ int flashrom_layout_new(struct flashrom_layout **const layout)
 	return 0;
 }
 
-/**
- * @brief Add another region to an existing layout.
- *
- * @param layout The existing layout.
- * @param start  Start address of the region.
- * @param end    End address (inclusive) of the region.
- * @param name   Name of the region.
- *
- * @return 0 on success,
- *         1 if out of memory.
- */
 int flashrom_layout_add_region(
 		struct flashrom_layout *const layout,
 		const size_t start, const size_t end, const char *const name)
@@ -418,31 +394,11 @@ _err_ret:
 	return 1;
 }
 
-/**
- * @brief Mark given region as included.
- *
- * @param layout The layout to alter.
- * @param name   The name of the region to include.
- *
- * @return 0 on success,
- *         1 if the given name can't be found.
- */
 int flashrom_layout_include_region(struct flashrom_layout *const layout, const char *name)
 {
 	return include_region(layout, name, NULL);
 }
 
-/**
- * @brief Get given region's offset and length.
- *
- * @param layout The layout to alter.
- * @param name   The name of the region.
- * @param start  The start address to be written.
- * @param len    The length of the region to be written.
- *
- * @return 0 on success,
- *         1 if the given name can't be found.
- */
 int flashrom_layout_get_region_range(struct flashrom_layout *const l, const char *name,
 			      unsigned int *start, unsigned int *len)
 {
@@ -455,11 +411,6 @@ int flashrom_layout_get_region_range(struct flashrom_layout *const l, const char
 	return 1;
 }
 
-/**
- * @brief Free a layout.
- *
- * @param layout Layout to free.
- */
 void flashrom_layout_release(struct flashrom_layout *const layout)
 {
 	if (!layout)
@@ -474,5 +425,3 @@ void flashrom_layout_release(struct flashrom_layout *const layout)
 	}
 	free(layout);
 }
-
-/** @} */ /* end flashrom-layout */