friedl@vsi.UUCP (Stephen J. Friedl) (07/18/88)
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@vsi.com {backbones}!vsi.com!friedl attmail!vsi!friedl
--------- Nancy Reagan on flood-control: "Just say Noah"----------beckenba@cit-vax.Caltech.Edu (Joe Beckenbach) (07/21/88)
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
guy@gorodish.Sun.COM (Guy Harris) (07/21/88)
> 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. No, it's not just information-hiding. It's also indicating that there may be other members in future implementations, for example. The SVID, and the System III/System V "stat" documentation, for example, do not show the "stat" structure, they just list some of the members; thus, a system that provides the 4.2BSD "stat" structure is not incompliant with the SVID nor incompatible with System V merely by virtue of having the 4.2BSD "stat" structure. (No complaints about "utime" being passed a pointer to "st_atime" and not working, please; the SVID and the S3/S5 documentation and "lint" library go out of their way to discourage this practice.) > 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. As a system programmer, I prefer getting the entire structure *only* when it's written to files or network connections, for example (and, in this modern world, dumping structures directly to files or network connections - *especially* to network connections - is often a Bad Thing; take 4BSD "talk" - please!). For most of the structures I have to deal with at that level of detail, the documentation of the exact layout is online in the include files, which tends to suffice.
henry@utzoo.uucp (Henry Spencer) (07/23/88)
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... By far the best way is to show just the members, introduced by text that says something like "this struct includes at least the following members, not necessarily in this order". The point here is that you may want to add more members, or rearrange existing ones, later. This usage puts people on notice that no silly tricks are allowed. (As a useful side effect, it also makes it even more likely that they will #include the header file rather than typing the structure in themselves.) Look at the wording in X3J11 or POSIX -- they do it this way. -- Anyone who buys Wisconsin cheese is| Henry Spencer at U of Toronto Zoology a traitor to mankind. --Pournelle |uunet!mnetor!utzoo! henry @zoo.toronto.edu
daveb@llama.rtech.UUCP (Dave Brower) (07/25/88)
In <7351@cit-vax.Caltech.Edu> beckenba@cit-vax.UUCP (Joe Beckenbach) writes: >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. 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@rtech.com <- FINALLY!