Path: utzoo!attcan!uunet!husc6!mailrus!ames!elroy!cit-vax!beckenba
From: beckenba@cit-vax.Caltech.Edu (Joe Beckenbach)
Newsgroups: comp.lang.c
Subject: Re: How to represent structs in text
Summary: What makes sense to me
Message-ID: <7351@cit-vax.Caltech.Edu>
Date: 21 Jul 88 01:23:04 GMT
References: <759@vsi.UUCP>
Reply-To: beckenba@cit-vax.UUCP (Joe Beckenbach)
Organization: California Institute of Technology
Lines: 51

OPINION ALERT! OPINION ALERT! :-) :-)

In article <759@vsi.UUCP> friedl@vsi.UUCP (Stephen J. Friedl) writes:
>     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):

	Showing just the members seems to indicate to me that the members
listed are definitely there, but other members might be as well which
should really not be tampered with. This is simply information-hiding
which might be better done implemented in software than by lack of reference
in the documentation.

	Showing the structure as given in the example:
>
>	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 */
>	};
>
	implies that the entire structure is as it appears, and the
above text can be typed in as is as a compatible structure type.


>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.

	Sorry to post instead, Steve, but I feel that this is a problem
which merits wider circulation, as ideally we *all* do documentation.
Choose whichever makes sense and implies what you need to have implied;
better yet, spell out a documentation practice, such as saying out front

"Structures displayed in their entirety have no other members implemented;
 structures displayed without surrounding braces may have additional members
 which are intentionally not mentioned."

	For system programmers and other down&dirty implementors, entire
structures should be the norm; end users deserve the watered-down partial
structure revelation normally; programmers need one or the other depending
on what level of detail they need.

		Joe Beckenbach
[We now return you to your regularly scheduled reality.... :-)]
-- 
Joe Beckenbach	beckenba@csvax.caltech.edu	Caltech 1-58, Pasadena CA 91125
Mars Observer Camera Project			Caltech Planetary Sciences Division
Live at 19200 baud. Power down young. Confuse hackers in between....  MOCvax