Merge tag 'doc-2024-10-rc6' of https://source.denx.de/u-boot/custodians/u-boot-efi

Pull request doc-2024-10-rc6

Documentation:

* Correct function descriptions that are not Sphinx conformant.
* Correct incorrect dependency CONFIG_USB_USB_GADGET in the ums command
  description.

cmd/efidebug.c

@@ -665,7 +665,7 @@ enum efi_lo_dp_part {
 };
 
 /**
- * create_lo_dp() - create a special device path for our Boot### option
+ * create_lo_dp_part() - create a special device path for our Boot### option
  *
  * @dev:	device
  * @part:	disk partition
@@ -1127,7 +1127,7 @@ static void show_efi_boot_opt(u16 *varname16)
 }
 
 /**
- * show_efi_boot_dump() - dump all UEFI load options
+ * do_efi_boot_dump() - dump all UEFI load options
  *
  * @cmdtp:	Command table
  * @flag:	Command flag

doc/usage/cmd/ums.rst

@@ -48,7 +48,7 @@ Configuration
 -------------
 
 The ums command is only available if CONFIG_CMD_USB_MASS_STORAGE=y
-and depends on CONFIG_USB_USB_GADGET and CONFIG_BLK.
+which depends on CONFIG_USB_GADGET_DOWNLOAD and CONFIG_BLK.
 
 Return value
 ------------

include/efi_variable.h

@@ -38,7 +38,7 @@ efi_status_t efi_get_variable_int(const u16 *variable_name,
 				  void *data, u64 *timep);
 
 /**
- * efi_set_variable() - set value of a UEFI variable
+ * efi_set_variable_int() - set value of a UEFI variable
  *
  * @variable_name:	name of the variable
  * @vendor:		vendor GUID

include/event.h

@@ -385,7 +385,7 @@ static inline int event_notify_null(enum event_t type)
 int event_uninit(void);
 
 /**
- * event_uninit() - Set up dynamic events
+ * event_init() - Set up dynamic events
  *
  * Init a list of dynamic event handlers, so that these can be added as
  * needed

include/expo.h

@@ -42,7 +42,7 @@ enum expoact_type {
  *
  * @type: Action type (EXPOACT_NONE if there is no action)
  * @select: Used for EXPOACT_POINT_ITEM and EXPOACT_SELECT
- * @id: ID number of the object affected.
+ * @select.id: ID number of the object affected.
  */
 struct expo_action {
 	enum expoact_type type;

include/getopt.h

@@ -20,11 +20,9 @@ struct getopt_state {
 	 * parsed all of @argv, then @index will equal @argc.
 	 */
 	int index;
-	/* private: */
 	/** @arg_index: Index within the current argument */
 	int arg_index;
 	union {
-		/* public: */
 		/**
 		 * @opt: Option being parsed when an error occurs. @opt is only
 		 * valid when getopt() returns ``?`` or ``:``.
@@ -35,7 +33,6 @@ struct getopt_state {
 		 * is only valid when getopt() returns an option character.
 		 */
 		char *arg;
-	/* private: */
 	};
 };
 

include/os.h

@@ -24,7 +24,7 @@ struct sandbox_state;
 int os_printf(const char *format, ...);
 
 /**
- * Access to the OS read() system call
+ * os_read() - access the OS read() system call
  *
  * @fd:		File descriptor as returned by os_open()
  * @buf:	Buffer to place data
@@ -34,7 +34,7 @@ int os_printf(const char *format, ...);
 ssize_t os_read(int fd, void *buf, size_t count);
 
 /**
- * Access to the OS write() system call
+ * os_write() - access the OS write() system call
  *
  * @fd:		File descriptor as returned by os_open()
  * @buf:	Buffer containing data to write
@@ -44,7 +44,7 @@ ssize_t os_read(int fd, void *buf, size_t count);
 ssize_t os_write(int fd, const void *buf, size_t count);
 
 /**
- * Access to the OS lseek() system call
+ * os_lseek() - access the OS lseek() system call
  *
  * @fd:		File descriptor as returned by os_open()
  * @offset:	File offset (based on whence)
@@ -67,7 +67,7 @@ off_t os_lseek(int fd, off_t offset, int whence);
 off_t os_filesize(int fd);
 
 /**
- * Access to the OS open() system call
+ * os_open() - access the OS open() system call
  *
  * @pathname:	Pathname of file to open
  * @flags:	Flags, like OS_O_RDONLY, OS_O_RDWR
@@ -162,7 +162,7 @@ void os_raise_sigalrm(void);
 void os_tty_raw(int fd, bool allow_sigs);
 
 /**
- * os_fs_restore() - restore the tty to its original mode
+ * os_fd_restore() - restore the tty to its original mode
  *
  * Call this to restore the original terminal mode, after it has been changed
  * by os_tty_raw(). This is an internal function.
@@ -207,14 +207,14 @@ void *os_realloc(void *ptr, size_t length);
 void os_usleep(unsigned long usec);
 
 /**
- * Gets a monotonic increasing number of nano seconds from the OS
+ * os_get_nsec() - get monotonically increasing number of nano seconds from OS
  *
- * Return:	a monotonic increasing time scaled in nano seconds
+ * Return:	a monotoniccally increasing time scaled in nano seconds
  */
 uint64_t os_get_nsec(void);
 
 /**
- * Parse arguments and update sandbox state.
+ * os_parse_args() - parse arguments and update sandbox state.
  *
  * @state:	sandbox state to update
  * @argc:	argument count

lib/efi_loader/efi_console.c

@@ -100,7 +100,7 @@ static int term_get_char(s32 *c)
 }
 
 /**
- * Receive and parse a reply from the terminal.
+ * term_read_reply() - receive and parse a reply from the terminal
  *
  * @n:		array of return values
  * @num:	number of return values expected

lib/efi_loader/efi_file.c

@@ -295,7 +295,7 @@ out:
 }
 
 /**
- * efi_file_open_()
+ * efi_file_open() - open file synchronously
  *
  * This function implements the Open service of the File Protocol.
  * See the UEFI spec for details.

lib/efi_loader/efi_rng.c

@@ -91,7 +91,7 @@ back:
 }
 
 /**
- * rng_getrng() - get random value
+ * getrng() - get random value
  *
  * This function implement the GetRng() service of the EFI random number
  * generator protocol. See the UEFI spec for details.

lib/efi_loader/efi_unicode_collation.c

@@ -266,7 +266,7 @@ static void EFIAPI efi_fat_to_str(struct efi_unicode_collation_protocol *this,
 }
 
 /**
- * efi_fat_to_str() - convert a utf-16 string to legal characters for a FAT
+ * efi_str_to_fat() - convert a utf-16 string to legal characters for a FAT
  *                    file name in an OEM code page
  *
  * @this:	unicode collation protocol instance