Use a more descriptive comment convention

[sunfishcode]

Currently many functions in rustix are documented with a comment that looks like this:

/// `openat(dirfd, path, oflags, mode)`—Opens a file.
///
/// POSIX guarantees that `openat` will use the lowest unused file descriptor,
/// however it is not safe in general to rely on this, as file descriptors may
/// be unexpectedly allocated on other threads or in libraries.
///
/// The `Mode` argument is only significant when creating a file.
///
/// # References
///  - [POSIX]
///  - [Linux]
///
/// [POSIX]: https://pubs.opengroup.org/onlinepubs/9699919799/functions/openat.html
/// [Linux]: https://man7.org/linux/man-pages/man2/open.2.html

It starts with a C-ish pseudocode corresponding to what the function does, followed by a short description. My idea was to highlight the correspondence to C, since all the OS documentation is written in terms of C, and rustix isn't currently in a position to have its own complete documentation for everything.

But perhaps it would be better to move the C-ish pseudo-code later, like this, so that the first line is just a description of the thing:

/// Opens a file.
///
/// POSIX guarantees that `openat` will use the lowest unused file descriptor,
/// however it is not safe in general to rely on this, as file descriptors may
/// be unexpectedly allocated on other threads or in libraries.
///
/// The `Mode` argument is only significant when creating a file.
///
/// # C pseudocode
///
/// ```c
/// openat(dirfd, path, oflags, mode)
/// ```
///
/// # References
///  - [POSIX]
///  - [Linux]
///
/// [POSIX]: https://pubs.opengroup.org/onlinepubs/9699919799/functions/openat.html
/// [Linux]: https://man7.org/linux/man-pages/man2/open.2.html

[cgwalters]

I happened to glance at move_into_thread_name_spaces() as a reference which doesn't use this, I guess because its Rust name differs from the C one, even though it's a (relatively) literal exposure of the API?

I do think the second style of having # C pseudocode below would be better.