How to represent structs in text

[Dave Brower]

In <7351 at cit-vax.Caltech.Edu> beckenba at cit-vax.UUCP (Joe Beckenbach) writes:
>OPINION ALERT! OPINION ALERT! :-) :-)
>
>In article <759 at vsi.UUCP> friedl at 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.

I am inclined to show the structure as it would be declared in real C,
with elipses indicating the (possible) presence of members with which
the user shouldn't muck.  This is from the splay tree library man page I
submitted to comp.unix:

	.PP
	The SPTREE structure declared in sptree.h should only be handled
	indirectly.  A pointer to an SPTREE is returned by
	.I spinit
	and should be handed blindly to other access functions.
	.PP
	The nodes in a splay tree are defined by the following structure,
	declared in sptree.h.
	.PP
	.nf
	typedef struct _spblk SPBLK;
	typedef struct _spblk
	{
	    .
	    .
	    .
	    char	*key;
	    char	*data;
	    char	*datb;
	};


I find exclusively textual descriptions opaque, and it's infuriating to
run across C that appears to be complete, but isn't.  There is a
fundamental problem with C here, which is the lack of a private/public
distinction.  C++ handles this much more nicely.

-dB




"Ready when you are Raoul!"
{amdahl, cpsc6a, mtxinu, sun, hoptoad}!rtech!daveb daveb at rtech.com <- FINALLY!