Date: Sat, 17 Mar 2001 00:30:52 +0000 (GMT) From: Terry Lambert <tlambert@primenet.com> To: mjacob@feral.com Cc: tlambert@primenet.com (Terry Lambert), jhb@FreeBSD.ORG (John Baldwin), arch@FreeBSD.ORG Subject: Re: man pages Message-ID: <200103170032.RAA20020@usr07.primenet.com> In-Reply-To: <Pine.LNX.4.21.0103161555550.773-100000@zeppo.feral.com> from "Matthew Jacob" at Mar 16, 2001 04:01:41 PM
next in thread | previous in thread | raw e-mail | index | archive | help
> > It seems to me that the function ou are documenting is machine > > specific, and should be named for the architecture/CPU/etc. to > > which it applies. > > Umm..., no, disable_intr *could* be a global block. Perhaps I didn't pick the > best example. > > It still remains that disable_intr disables interrupts. restore_intr restores > the state that existed prior to the disable_intr call. That's a useless thing to say, particularly, when disabling interrupts is carefully worded to be devoid of demantics. > The only thing which I think people have problems with is my running around > saying "do *not* say whether it's global or cpu-local". No, that's not my objection. > I'm having trouble following this. Let me try and reiterate (putting on my > Solaris DDI/DKI team hat, FWIBWBN) that disable_intr/restore_intr would be > required to be on all platforms, but might have subtly different meanings. [ ... ] > Jeez. I'm sorry, Terry. I'm not following this at all. Let me try to be plain about this: quit documenting what it does, and instead, document when and why I would want to use it. If you document what it does, I get the choice of calling it when *I* think it might be useful based on my interpreation of what it does. If you document when and why I would want to use it, it takes away the ambiguity, and drastically reduces the potential for error. As a shining example: msync(). What does msync() do? It's an explicit VM and buffer cache synchronization call, which flushes unwritten changes to a VM object mapped into a user space program back to the buffer cache. Is knowing this useful? No; here's why: 1) Knowing this doesn't tell me that on systems with a coherent VM and buffer cache, synchronization is automatic, and the reason to use it in my program is to ensure portability to systems without a coherent VM and buffer cache; in other words, on some system it is (or is supposed to be) a NOP. . 2) Knowing this doesn't tell me that flushing it to buffer cache is not the same thing as flushing it to stable storage... there's no indication of the fact that the buffer cache is an intermediate layer. 3) Naming it "msync()" leads me to belive that it is to a write to an mmap()'ed region, what "fsync() is to a write() to an open()'ed file; it's not. Clearly, msync() could be better documented, and we would all be better off for it; but it's not. Someone thought it would be a good idea to document what it does -- the interface -- and not when and why I would want to use it. So we get all this code that calls msync() everywhere the author thought they knew what msync() does would be useful, instead of where it needed to be called for portability, or where it would actually be useful. Does this make more sense now? I think the name is misleading, and I think leaving the man pages intentionally ambiguous is worse than not having them, and I think that a relatively new user looking at them or the code would still not have a good idea of when and why they'd want to use the calls. As it is, even with the suggested intntional ambiguities called out as being intentional, it'd take a language lawyer with a clear head to be able to use the thing correctly and not shoot someone on a different architecture in the foot. Terry Lambert terry@lambert.org --- Any opinions in this posting are my own and not those of my present or previous employers. To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-arch" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?200103170032.RAA20020>