Re: src/sys/vfs ANSIfication

[Matthew Dillon <dillon@xxxxxxxxxxxxxxxxxxxx>]

:While on the subject, and well before I begin committing these, I should
:mention - there are a LOT of function definitions that look like this:
:
:static int
:hpfs_ioctl (
:	struct vop_ioctl_args /* {
:		struct vnode *a_vp;
:		u_long a_command;
:		caddr_t a_data;
:		int a_fflag;
:		struct ucred *a_cred;
:		struct proc *a_p;
:	} */ *ap)
:
:I (perhaps not thinking too clearly) reformatted these like
:
:static int
:hpfs_ioctl(struct vop_ioctl_args /* {
:		struct vnode *a_vp;
:		u_long a_command;
:		caddr_t a_data;
:		int a_fflag;
:		struct ucred *a_cred;
:		struct proc *a_p;
:	   } */ *ap)

    It's messy either way :-).  When I went about and started
    'fixing' these sorts of declarations in the kernel tree,
    particular the more complex syscalls, I moved the
    comments to above the procedure rather then embedded in the
    procedure arguments.  e.g. like this:

/*
 * socketpair(int domain, int type, int protocol, int *rsv)
 */
int
socketpair(struct socketpair_args *uap)
{
        int error, sockv[2];

        error = kern_socketpair(uap->domain, uap->type, uap->protocol, sockv);
            
        if (error == 0)
                error = copyout(sockv, uap->rsv, sizeof(sockv));
        return (error);
}

    Which is much more readable.

    However, I am not requiring that you do this.  It's a lot of
    work, only do it if you think it looks better and you have a
    lot of time to burn cleaning these up.  I don't think even I
    did it in every case... my fingerse got tired :-)
    
:...
:But I realize as well, that Matt has mentioned that comments inline in
:argument lists are not the prettiest thing in the world.  And these
:ones strike me as particularly clunky-looking...
:
:But I assume the reason there are comments here in the first place is
:because these structures (like struct vop_ioctl_args) are not statically
:defined, but rather dynamically created as part of the build process.

    The comments are in there because the structures are otherwise
    opaque.  Consider the socketpair() procedure above.  If all we
    have is the 'struct socketpair_args *uap' argument we really have
    no idea what elements are in that structure.  Because this sort
    of structure is used for *ALL* system calls, ioctls, etc... and
    because it is a different structure for each one, the contents
    of the structure are included in comments so a programer trying
    to read the code can stay sane.

					-Matt
					Matthew Dillon 
					<dillon@xxxxxxxxxxxxx>

:Is there maybe a better way to do this?  Some way so that we can say
:
:Just thought I'd raise the question before the bits start flying...
:
:-Chris