Date: Thu, 11 Jan 2001 15:51:33 +0000 (GMT) From: Terry Lambert <tlambert@primenet.com> To: gibbs@scsiguy.com (Justin T. Gibbs) Cc: des@ofug.org (Dag-Erling Smorgrav), freebsd-arch@FreeBSD.ORG Subject: Re: Proposed chage to sbuf semantics. Message-ID: <200101111551.IAA16079@usr08.primenet.com> In-Reply-To: <200101111503.f0BF3ws29178@aslan.scsiguy.com> from "Justin T. Gibbs" at Jan 11, 2001 08:03:58 AM
next in thread | previous in thread | raw e-mail | index | archive | help
> >> I didn't read the man page, I read the code. > > > >This is FreeBSD, not Linux. > > I hardly see how this matters. Private interfaces should be > documented as such in the header file (or not exist there at all) > as well as the man page. Sometimes reading the code is easier than > reading the man page and regardless of how you feel about the > necessity of reading the man page the fact is that some people > wont. The claim that "This is FreeBSD, not Linux." should probably have been "This is FreeBSD, not Linux; therefore the code is more authoritative than the documentation, since documentation will usually lag the code by a significant amount.". If the macros are not for externa use, then they should not be in the external namespace, period. If they need to be accessed in multiple source files, then something like: #ifdef _INTERNAL_SBUF_ ... #endif /* _INTERNAL_SBUF_*/ should surround their use, and that manifest should be defined before inclusion of the header file to allow their use (this is a gross hack, in any case: more probably, the macros should be eliminated to the point they exist in only one source file, not a header file). My opinion is that if something is defined in scope, I should feel free to use it, since it was obviously intended by the author that it be available for my use. If the author didn't intend that, then the author has made an error an should correct it. On a side not, it really doesn't matther _what_ the documentation says, unless an interface has stabilized to the point where it will not change over a relatively large period of time (long enough to publish a book about it, and have the book continue to be correct for the period of a year, if not longer). FreeBSD does not have this level of DDI/DKI, though one hopes that it eventually will, and there is no policy that interfaces are not permitted to change unless accompanied by accurate documentation changes, as well. Either the macros are incorrectly scoped, or the documentation is incorrect, but _something_ is wrong here, and needs to be corrected. I personally think that what Justin is trying to do _should_ be possible, and I don't really understand why there is a pseudo-requirement that the api be made up of function calls, and not macros; certainly, this is not a global requirement, or someone would "fix" the select() interface, and other code where macros are used. Also, pretending that macros are functions by changing naming conventions in violation of the existing style requirements makes no sense to me; perhaps it was intended that they be inlines instead of macros? Since inlines live in the function convention namespace, this makes a heck of a lot more sense than hiding macros there... 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?200101111551.IAA16079>