[PATCH v3 7/8] sandbox: update function descriptions in os.h
Simon Glass
sjg at chromium.org
Tue Nov 3 16:11:39 CET 2020
Hi Heinrich,
On Mon, 2 Nov 2020 at 17:13, Heinrich Schuchardt <xypron.glpk at gmx.de> wrote:
>
> 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
There are so many different styles floating around that I am not even
sure what this new one is called.
But it does suggest there is a single-line option:
/** @foobar: Single line description. */
int foobar;
It is quite a bit less verbose and use up a lot less vertical screen
real estate.
Reviewed-by: Simon Glass <sjg at chromium.org>
Regards,
Simon
More information about the U-Boot
mailing list