[prev in list] [next in list] [prev in thread] [next in thread] 

List:       linux-man
Subject:    AW: Formatting very long function parameters
From:       Walter Harms <wharms () bfs ! de>
Date:       2021-03-11 11:44:22
Message-ID: d461cc53f343497f81c6d69ddd6e39e0 () bfs ! de
[Download RAW message or body]

hi,
since no one answered i will give my personal view:
I would go for A)
if that does not fit try to compress names (if possible)
and ignore the 78 Char boundary.

NTL:
having names that long is questionable in the first place
(not your fault, i know).

re,
 wh
________________________________________
Von: Alejandro Colomar (man-pages) <alx.manpages@gmail.com>
Gesendet: Montag, 8. M=E4rz 2021 14:54:01
An: Michael Kerrisk (man-pages)
Cc: linux-man
Betreff: Formatting very long function parameters

Hi Michael,

I have a problem with pthread_mutexattr_getpshared(3).
After adding 'restrict', the first parameter alone would use 81 columns,
so I came with 3 options:

A)      Move the parameter to a new line,
        leaving the open parenthesis at the end of a line.

[
        int pthread_mutexattr_getpshared(
                                      const pthread_mutexattr_t
*restrict attr,
                                      int *restrict pshared);
        int pthread_mutexattr_setpshared(pthread_mutexattr_t *attr,
                                      int pshared);
]

B)      Compact the pointer to use only 80 columns,
        by deleting a cosmetic whitespace,
        and exceptionally ignore the 78-column right margin.

[
        int pthread_mutexattr_getpshared(const
pthread_mutexattr_t*restrict attr,
                                         int *restrict pshared);
        int pthread_mutexattr_setpshared(pthread_mutexattr_t *attr,
                                         int pshared);
]

C)      (What POSIX does) Break the 1st parameter at the pointer:

[
        int pthread_mutexattr_getpshared(const pthread_mutexattr_t
                                         *restrict attr,
                                         int *restrict pshared);
        int pthread_mutexattr_setpshared(pthread_mutexattr_t *attr,
                                         int pshared);
]


I did the 1st one, but I'm not sure about it.  Do you have any preference?

This is only problematic when both the function name and the 1st
parameter are very long, which is rare, so it shouldn't appear in many
pages.  I don't expect to find another case.  Option B) might not be an
option if there are more like this (if those use >82 columns).

Thanks,

Alex

--
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/
[prev in list] [next in list] [prev in thread] [next in thread]