tech-pkg archive

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index][Old Index]

Re: CVS commit: src



hi,

> On Tue, Jan 26, 2010 at 12:25:00PM +0000, David Brownlee wrote:
>  > > ... or in a book about the kernel. ?Section 9 describes how to use kernel
>  > > facilities, not how they work internally. ?By documenting this item you
>  > > give the impression of availability and stability, neither of which is
>  > > provided.
>  > 
>  > I think its safe to say that the best place to keep implementation
>  > documentation is with the code (at least in the same tree) so it can
>  > track changes, and from there its a small step to shipping the
>  > documentation with the system.
> 
> ISTM that section 9 is an appropriate place for both interface and
> implementation docs. In the (few) cases where we actually have an
> interface, as opposed to "some exposed pieces of the implementation",
> the documentation should be clear on which is which and which
> properties of the implementation are actually guaranteed by the
> interface and which aren't.

let's stop being too generic and go back to the change in question.
do you think this man page is an appropriate place for these functions?

these functions are merely internals of some MD implementations.
describing them in this man page gives the wrong impression that
it's available for every ports and MI code can use them.

dyoung, can you please back the change out?

(why tech-pkg, btw?)

YAMAMOTO Takashi


Home | Main Index | Thread Index | Old Index