Re: [PATCH 1/3] genclk: add generic framework for managing clocks.

[Russell King <rmk+lkml@arm.linux.org.uk>]

On Sun, Jul 13, 2008 at 02:23:17PM -0700, Andrew Morton wrote:
> On Sun, 13 Jul 2008 14:12:32 -0700 David Brownell <david-b@pacbell.net> wrote:
> 
> > On Saturday 12 July 2008, Andrew Morton wrote:
> > > > +EXPORT_SYMBOL(clk_get_parent);
> > > 
> > > As this is a new kernel-wide utility library, it is appropriate that
> > > all of its public interfaces (at least) be documented. __An appropriate
> > > way of doing that is via kerneldoc annotation. __Please don't forget to
> > > document return values and call environment prerequisites (eg: requires
> > > foo_lock, may be called from interrupt context, etc, etc).
> > 
> > That is, the stuff that's not already documented in <linux/clk.h>;
> > that's where clk_get_parent() is documented, for example.
> 
> argh.  That's why I missed it - please don't document stuff in header
> files.  The usual approach is to document interfaces at the
> implementation site.

That doesn't work.  In this case, linux/clk.h _is_ the only source of
the API.  The API is just a defined set of functions.

How an architecture or machine class implements it is at the discressiom
of whoever's writing that code.  The point being, that we have a fixed
core API which drivers can use which is portable across different SoCs.

However, there certainly are implementation specific issues which
architecture code needs to know about - hence why the implementation
has (until genclk) been left completely up to that code to decide and
implement the interface.

So, the only place for that documentation is the header file.  Documenting
an implementation will just confuse the issue and lead people into thinking
that it somehow represents the way things should be done.

Even genclk doesn't represent "The Way Things Should Be Done" - it's just
yet another implementation of the interface.

-- 
Russell King
 Linux kernel    2.6 ARM Linux   - http://www.arm.linux.org.uk/
 maintainer of: