How to represent structs in text

[Stephen J. Friedl]

Hi folks,

     I am looking for opinions on how to represent structs in text.
The two schools of thought are (a) show the full struct declaration
and (b) show just the members.  For example, take the following two
samples used w/o permission from intro(2):

#------------

"Sem_perm" is an ipc_perm structure that specifies the semaphore
operation permission (see below).  This structure includes the
following members:

	ushort	cuid;	/* creater user id.
	ushort	cgid;	/* creator group id */
	ushort	uid;	/* user id */
	ushort	gid;	/* group id */
	ushort	mode;	/* r/a permissions */


#------------

"Sem_perm" is an ipc_perm structure that specifies the semaphore
operation permission (see below).  This structure is:

	struct sem_perm {
		ushort	cuid;	/* creater user id.
		ushort	cgid;	/* creator group id */
		ushort	uid;	/* user id */
		ushort	gid;	/* group id */
		ushort	mode;	/* r/a permissions */
	};

#------------

I find the second much easier to read, as the struct { } gives me
an easy context, but obviously there are those who prefer the first.
I'm doing some documentation reviews, and I would like very much to
hear opinions (even just a quick yes/no) on this topic via email.

     Thanks,
     Steve

-- 
Steve Friedl    V-Systems, Inc.  +1 714 545 6442    3B2-kind-of-guy
friedl at vsi.com     {backbones}!vsi.com!friedl    attmail!vsi!friedl
--------- Nancy Reagan on flood-control: "Just say Noah"----------