From fe1a81c1a47737d3ce6b6855a05468b7546d4982 Mon Sep 17 00:00:00 2001
From: Heinrich Schuchardt <xypron.glpk@gmx.de>
Date: Thu, 5 Sep 2019 20:37:13 +0200
Subject: [PATCH] doc: UEFI API documentation

Add some more files to the UEFI API documentation.

Correct some Sphinx comments.

Signed-off-by: Heinrich Schuchardt <xypron.glpk@gmx.de>
---
 doc/api/efi.rst              | 33 +++++++++++++++++++++++++++++++++
 lib/efi_loader/efi_console.c | 11 ++++++-----
 lib/efi_loader/efi_gop.c     |  2 +-
 lib/efi_loader/efi_net.c     |  9 ++++++---
 4 files changed, 46 insertions(+), 9 deletions(-)

diff --git a/doc/api/efi.rst b/doc/api/efi.rst
index 39e2dbae0b..2ca344932e 100644
--- a/doc/api/efi.rst
+++ b/doc/api/efi.rst
@@ -103,3 +103,36 @@ Block device driver
 
 .. kernel-doc:: lib/efi_driver/efi_block_device.c
    :internal:
+
+Protocols
+---------
+
+Block IO protocol
+~~~~~~~~~~~~~~~~~
+
+.. kernel-doc:: lib/efi_loader/efi_disk.c
+   :internal:
+
+File protocol
+~~~~~~~~~~~~~
+
+.. kernel-doc:: lib/efi_loader/efi_file.c
+   :internal:
+
+Graphical output protocol
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. kernel-doc:: lib/efi_loader/efi_gop.c
+   :internal:
+
+Network protocols
+~~~~~~~~~~~~~~~~~
+
+.. kernel-doc:: lib/efi_loader/efi_net.c
+   :internal:
+
+Text IO protocols
+~~~~~~~~~~~~~~~~~
+
+.. kernel-doc:: lib/efi_loader/efi_console.c
+   :internal:
diff --git a/lib/efi_loader/efi_console.c b/lib/efi_loader/efi_console.c
index 5109017796..a55e4b33ec 100644
--- a/lib/efi_loader/efi_console.c
+++ b/lib/efi_loader/efi_console.c
@@ -219,9 +219,9 @@ static bool cout_mode_matches(struct cout_mode *mode, int rows, int cols)
 /**
  * query_console_serial() - query console size
  *
- * @rows	pointer to return number of rows
- * @columns	pointer to return number of columns
- * Returns	0 on success
+ * @rows:	pointer to return number of rows
+ * @cols:	pointer to return number of columns
+ * Returns:	0 on success
  */
 static int query_console_serial(int *rows, int *cols)
 {
@@ -464,7 +464,7 @@ struct efi_simple_text_output_protocol efi_con_out = {
  * struct efi_cin_notify_function - registered console input notify function
  *
  * @link:	link to list
- * @data:	key to notify
+ * @key:	key to notify
  * @function:	function to call
  */
 struct efi_cin_notify_function {
@@ -482,6 +482,7 @@ static LIST_HEAD(cin_notify_functions);
  * set_shift_mask() - set shift mask
  *
  * @mod:	Xterm shift mask
+ * @key_state:  receives the state of the shift, alt, control, and logo keys
  */
 void set_shift_mask(int mod, struct efi_key_state *key_state)
 {
@@ -504,7 +505,7 @@ void set_shift_mask(int mod, struct efi_key_state *key_state)
  *
  * This gets called when we have already parsed CSI.
  *
- * @modifiers:  bit mask (shift, alt, ctrl)
+ * @key_state:  receives the state of the shift, alt, control, and logo keys
  * @return:	the unmodified code
  */
 static int analyze_modifiers(struct efi_key_state *key_state)
diff --git a/lib/efi_loader/efi_gop.c b/lib/efi_loader/efi_gop.c
index cad509bfea..1511e3bdb4 100644
--- a/lib/efi_loader/efi_gop.c
+++ b/lib/efi_loader/efi_gop.c
@@ -319,7 +319,7 @@ static efi_status_t gop_blt_vid_to_buf(struct efi_gop *this,
  * details.
  *
  * @this:		the graphical output protocol
- * @model_number:	the mode to be set
+ * @mode_number:	the mode to be set
  * Return:		status code
  */
 static efi_status_t EFIAPI gop_set_mode(struct efi_gop *this, u32 mode_number)
diff --git a/lib/efi_loader/efi_net.c b/lib/efi_loader/efi_net.c
index cff6332a68..82d2595847 100644
--- a/lib/efi_loader/efi_net.c
+++ b/lib/efi_loader/efi_net.c
@@ -399,7 +399,7 @@ out:
  * Protocol. See the UEFI spec for details.
  *
  * @this:		the instance of the Simple Network Protocol
- * @readwrite:		true for read, false for write
+ * @read_write:		true for read, false for write
  * @offset:		offset in NVRAM
  * @buffer_size:	size of buffer
  * @buffer:		buffer
@@ -639,6 +639,9 @@ out:
  * efi_net_set_dhcp_ack() - take note of a selected DHCP IP address
  *
  * This function is called by dhcp_handler().
+ *
+ * @pkt:	packet received by dhcp_handler()
+ * @len:	length of the packet received
  */
 void efi_net_set_dhcp_ack(void *pkt, int len)
 {
@@ -668,8 +671,8 @@ static void efi_net_push(void *pkt, int len)
  *
  * This notification function is called in every timer cycle.
  *
- * @event	the event for which this notification function is registered
- * @context	event context - not used in this function
+ * @event:	the event for which this notification function is registered
+ * @context:	event context - not used in this function
  */
 static void EFIAPI efi_network_timer_notify(struct efi_event *event,
 					    void *context)
-- 
2.25.1