os.sendfile() flags improperly ordered in documentation

[calestyo]

Bug report

There are some minor issues in the documentation for which I'm about to submit MRs:

1. There's some bad ordering around os.sendfile(), it seems to make no sense that the os.set_blocking() function comes in-between the os.sendfile() function and its flags.
2. Also, the flags could possibly be joined into one section

cpython/Doc/library/os.rst

Lines 1542 to 1618 in cc2cf85

	.. function:: sendfile(out_fd, in_fd, offset, count)
	sendfile(out_fd, in_fd, offset, count, headers=(), trailers=(), flags=0)
	Copy *count* bytes from file descriptor *in_fd* to file descriptor *out_fd*
	starting at *offset*.
	Return the number of bytes sent. When EOF is reached return ``0``.
	The first function notation is supported by all platforms that define
	:func:`sendfile`.
	On Linux, if *offset* is given as ``None``, the bytes are read from the
	current position of *in_fd* and the position of *in_fd* is updated.
	The second case may be used on macOS and FreeBSD where *headers* and
	*trailers* are arbitrary sequences of buffers that are written before and
	after the data from *in_fd* is written. It returns the same as the first case.
	On macOS and FreeBSD, a value of ``0`` for *count* specifies to send until
	the end of *in_fd* is reached.
	All platforms support sockets as *out_fd* file descriptor, and some platforms
	allow other types (e.g. regular file, pipe) as well.
	Cross-platform applications should not use *headers*, *trailers* and *flags*
	arguments.
	.. availability:: Unix, not Emscripten, not WASI.
	.. note::
	For a higher-level wrapper of :func:`sendfile`, see
	:meth:`socket.socket.sendfile`.
	.. versionadded:: 3.3
	.. versionchanged:: 3.9
	Parameters *out* and *in* was renamed to *out_fd* and *in_fd*.
	.. function:: set_blocking(fd, blocking, /)
	Set the blocking mode of the specified file descriptor. Set the
	:data:`O_NONBLOCK` flag if blocking is ``False``, clear the flag otherwise.
	See also :func:`get_blocking` and :meth:`socket.socket.setblocking`.
	.. availability:: Unix, Windows.
	The function is limited on Emscripten and WASI, see
	:ref:`wasm-availability` for more information.
	On Windows, this function is limited to pipes.
	.. versionadded:: 3.5
	.. versionchanged:: 3.12
	Added support for pipes on Windows.
	.. data:: SF_NODISKIO
	SF_MNOWAIT
	SF_SYNC
	Parameters to the :func:`sendfile` function, if the implementation supports
	them.
	.. availability:: Unix, not Emscripten, not WASI.
	.. versionadded:: 3.3
	.. data:: SF_NOCACHE
	Parameter to the :func:`sendfile` function, if the implementation supports
	it. The data won't be cached in the virtual memory and will be freed afterwards.
	.. availability:: Unix, not Emscripten, not WASI.
	.. versionadded:: 3.11

Checklist

• I am confident this is a bug in CPython, not a bug in a third-party project
• I have searched the CPython issue tracker, and am confident this bug has not been reported before

Linked PRs

• gh-107924: re-order os.sendfile() flag documentation #107926
• [3.12] gh-107924: re-order os.sendfile() flag documentation (GH-107926) #109099
• [3.11] gh-107924: re-order os.sendfile() flag documentation (#107926) #109178

[AA-Turner]

@Eclips4 note that you can have a 'docs bug'. The four type- labels act orthoganally to the "area" labels (docs, stdlib, interpreter-core, tests, extension-modules). See https://devguide.python.org/triage/labels/.

A

[AA-Turner]

@calestyo please could you split your PR into two separate PRs, one for each distinct issue?

A

[calestyo]

@AA-Turner split out the stuff regarding mknod() in a separate issue and made this issue only about the ordering of sendfile() and its flags.

So I'd guess the MR for this one could be merged.