[PATCH 01/11] dix: Refactor block and wakup handlers

[Mark Kettenis]

> Date: Tue, 4 Jan 2011 12:26:13 +0200
> From: Pauli Nieminen <ext-pauli.nieminen at nokia.com>
> 
> On 03/01/11 13:23 -0800, ext Alan Coopersmith wrote:
> > On 12/31/10 09:30 AM, Pauli wrote:
> > > From: Pauli Nieminen <ext-pauli.nieminen at nokia.com>
> > > 
> > > It is common use case in server that only block or wakeup handler is
> > > used. To provide API for that case block handlers have to be split to
> > > separate structures.
> > > 
> > > +extern _X_EXPORT Bool RegisterBlockHandler(
> > > +    BlockHandlerProcPtr /*blockHandler*/,
> > > +    pointer /*blockData*/);
> > > +
> > > +extern _X_EXPORT void RemoveBlockHandler(
> > > +    BlockHandlerProcPtr /*blockHandler*/,
> > > +    pointer /*blockData*/);
> > > +
> > > +extern _X_EXPORT Bool RegisterWakeupHandler(
> > > +    WakeupHandlerProcPtr /*wakeupHandler*/,
> > > +    pointer /*blockData*/);
> > > +
> > > +extern _X_EXPORT void RemoveWakeupHandler(
> > > +    WakeupHandlerProcPtr /*wakeupHandler*/,
> > > +    pointer /*blockData*/);
> > > +
> > 
> > Seems like an excellent solution to the problem.   The docs should be
> > updated to match though, as in the attached patch you can merge into
> > this one.   (Yes, the style of the function declarations in those docs
> > still needs love, this matches the existing style for now.)
> >
> 
> Right. I'm going to add the documentation patch.
> 
> Looking at documentation. Is there any reason why it isn't embedded in code?
> 
> That would probably increase chances that developer would notice any stale
> information in docs.
> 
> Of course converting format is a lot work but maybe it could be automated.

In my experience documentation generated from annotations in the
source code tends to be worse than documentation that is maintained
seperately.  Probably because it ends up to be an aggregation of a lot
of little fragments that were written out of context.