[PATCH v3 7/8] sandbox: update function descriptions in os.h
Heinrich Schuchardt
xypron.glpk at gmx.de
Tue Nov 3 01:13:44 CET 2020
Am 3. November 2020 01:06:00 MEZ schrieb Simon Glass <sjg at chromium.org>:
>Hi Heinrich,
>
>On Tue, 27 Oct 2020 at 13:29, Heinrich Schuchardt <xypron.glpk at gmx.de>
>wrote:
>>
>> Use Sphinx style function descriptions.
>>
>> Signed-off-by: Heinrich Schuchardt <xypron.glpk at gmx.de>
>> ---
>> v3:
>> no change
>> v2:
>> new patch
>> ---
>> include/os.h | 223
>++++++++++++++++++++++++++++++---------------------
>> 1 file changed, 130 insertions(+), 93 deletions(-)
>>
>> diff --git a/include/os.h b/include/os.h
>> index 88dfb71c1a..1fe44f3510 100644
>> --- a/include/os.h
>> +++ b/include/os.h
>> @@ -19,30 +19,30 @@ struct sandbox_state;
>> /**
>> * Access to the OS read() system call
>> *
>> - * \param fd File descriptor as returned by os_open()
>> - * \param buf Buffer to place data
>> - * \param count Number of bytes to read
>> - * \return number of bytes read, or -1 on error
>> + * @fd: File descriptor as returned by os_open()
>> + * @buf: Buffer to place data
>> + * @count: Number of bytes to read
>> + * Return: number of bytes read, or -1 on error
>> */
>> ssize_t os_read(int fd, void *buf, size_t count);
>>
>> /**
>> * Access to the OS write() system call
>> *
>> - * \param fd File descriptor as returned by os_open()
>> - * \param buf Buffer containing data to write
>> - * \param count Number of bytes to write
>> - * \return number of bytes written, or -1 on error
>> + * @fd: File descriptor as returned by os_open()
>> + * @buf: Buffer containing data to write
>> + * @count: Number of bytes to write
>> + * Return: number of bytes written, or -1 on error
>> */
>> ssize_t os_write(int fd, const void *buf, size_t count);
>>
>> /**
>> * Access to the OS lseek() system call
>> *
>> - * \param fd File descriptor as returned by os_open()
>> - * \param offset File offset (based on whence)
>> - * \param whence Position offset is relative to (see below)
>> - * \return new file offset
>> + * @fd: File descriptor as returned by os_open()
>> + * @offset: File offset (based on whence)
>> + * @whence: Position offset is relative to (see below)
>> + * Return: new file offset
>> */
>> off_t os_lseek(int fd, off_t offset, int whence);
>>
>> @@ -54,9 +54,9 @@ off_t os_lseek(int fd, off_t offset, int whence);
>> /**
>> * Access to the OS open() system call
>> *
>> - * \param pathname Pathname of file to open
>> - * \param flags Flags, like OS_O_RDONLY, OS_O_RDWR
>> - * \return file descriptor, or -1 on error
>> + * @pathname: Pathname of file to open
>> + * @flags: Flags, like OS_O_RDONLY, OS_O_RDWR
>> + * Return: file descriptor, or -1 on error
>> */
>> int os_open(const char *pathname, int flags);
>>
>> @@ -68,42 +68,42 @@ int os_open(const char *pathname, int flags);
>> #define OS_O_TRUNC 01000
>>
>> /**
>> - * Access to the OS close() system call
>> + * os_close() - access to the OS close() system call
>> *
>> - * \param fd File descriptor to close
>> - * \return 0 on success, -1 on error
>> + * @fd: File descriptor to close
>> + * Return: 0 on success, -1 on error
>> */
>> int os_close(int fd);
>>
>> /**
>> - * Access to the OS unlink() system call
>> + * os_unlink() - access to the OS unlink() system call
>> *
>> - * \param pathname Path of file to delete
>> - * \return 0 for success, other for error
>> + * @pathname: Path of file to delete
>> + * Return: 0 for success, other for error
>> */
>> int os_unlink(const char *pathname);
>>
>> /**
>> - * Access to the OS exit() system call
>> + * os_exit() - access to the OS exit() system call
>> *
>> * This exits with the supplied return code, which should be 0 to
>indicate
>> * success.
>> *
>> - * @param exit_code exit code for U-Boot
>> + * @exit_code: exit code for U-Boot
>> */
>> void os_exit(int exit_code) __attribute__((noreturn));
>>
>> /**
>> - * Put tty into raw mode to mimic serial console better
>> + * os_tty_raw() - put tty into raw mode to mimic serial console
>better
>> *
>> - * @param fd File descriptor of stdin (normally 0)
>> - * @param allow_sigs Allow Ctrl-C, Ctrl-Z to generate signals
>rather than
>> - * be handled by U-Boot
>> + * @fd: File descriptor of stdin (normally 0)
>> + * @allow_sigs: Allow Ctrl-C, Ctrl-Z to generate signals
>rather than
>> + * be handled by U-Boot
>> */
>> void os_tty_raw(int fd, bool allow_sigs);
>>
>> /**
>> - * Restore the tty to its original mode
>> + * os_fs_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.
>> @@ -111,144 +111,180 @@ void os_tty_raw(int fd, bool allow_sigs);
>> void os_fd_restore(void);
>>
>> /**
>> - * Acquires some memory from the underlying os.
>> + * os_malloc() - aquires some memory from the underlying os.
>> *
>> - * \param length Number of bytes to be allocated
>> - * \return Pointer to length bytes or NULL on error
>> + * @length: Number of bytes to be allocated
>> + * Return: Pointer to length bytes or NULL on error
>> */
>> void *os_malloc(size_t length);
>>
>> /**
>> - * Free memory previous allocated with os_malloc()
>> + * os_free() - free memory previous allocated with os_malloc()
>> *
>> * This returns the memory to the OS.
>> *
>> - * \param ptr Pointer to memory block to free
>> + * @ptr: Pointer to memory block to free
>> */
>> void os_free(void *ptr);
>>
>> /**
>> - * Access to the usleep function of the os
>> + * os_usleep() - access to the usleep function of the os
>> *
>> - * \param usec Time to sleep in micro seconds
>> + * @usec: time to sleep in micro seconds
>> */
>> void os_usleep(unsigned long usec);
>>
>> /**
>> * Gets a monotonic increasing number of nano seconds from the OS
>> *
>> - * \return A monotonic increasing time scaled in nano seconds
>> + * Return: a monotonic increasing time scaled in nano seconds
>> */
>> uint64_t os_get_nsec(void);
>>
>> /**
>> * Parse arguments and update sandbox state.
>> *
>> - * @param state Sandbox state to update
>> - * @param argc Argument count
>> - * @param argv Argument vector
>> - * @return 0 if ok, and program should continue;
>> - * 1 if ok, but program should stop;
>> - * -1 on error: program should terminate.
>> + * @state: sandbox state to update
>> + * @argc: argument count
>> + * @argv: argument vector
>> + * Return:
>> + * * 0 if ok, and program should continue
>> + * * 1 if ok, but program should stop
>> + * * -1 on error: program should terminate
>> */
>> int os_parse_args(struct sandbox_state *state, int argc, char
>*argv[]);
>>
>> /*
>> + * enum os_dirent_t - type of directory entry
>> + *
>> * Types of directory entry that we support. See also
>os_dirent_typename in
>> * the C file.
>> */
>> enum os_dirent_t {
>> - OS_FILET_REG, /* Regular file */
>> - OS_FILET_LNK, /* Symbolic link */
>> - OS_FILET_DIR, /* Directory */
>> - OS_FILET_UNKNOWN, /* Something else */
>> -
>> + /**
>> + * @OS_FILET_REG: regular file
>> + */
>> + OS_FILET_REG,
>
>Maybe I missed your response about a similar thing with
>global_data.h...can we not do this?
>
>OS_FILET_REG, /**< @OS_FILET_REG: regular file */
>
>or
>
>OS_FILET_REG, /**< regular file */
>
>> + /**
>> + * @OS_FILET_LNK: symbolic link
>> + */
>
>or even:
>
>/** @OS_FILET_LNK: symbolic link */
>
>> + OS_FILET_LNK,
>> + /**
>> + * @OS_FILET_DIR: directory
>> + */
>
>Regards,
>Simon
We want to follow the Linux documentation style. Otherwise we cannot profit from the upstream scripts.
https://www.kernel.org/doc/html/latest/doc-guide/kernel-doc.html#structure-union-and-enumeration-documentation
Best regards
Heinrich
More information about the U-Boot
mailing list