Re: [PATCH 1/7] lguest: documentation pt I: Preparation

[Randy Dunlap <rdunlap@xenotime.net>]

On Mon, 23 Jul 2007 17:12:38 -0700 Andrew Morton wrote:

> On Sat, 21 Jul 2007 11:17:58 +1000
> Rusty Russell <rusty@rustcorp.com.au> wrote:
> 
> > The netfilter code had very good documentation: the Netfilter Hacking
> > HOWTO.  Noone ever read it.
> > 
> > So this time I'm trying something different, using a bit of
> > Knuthiness.  Start with drivers/lguest/README.
> 
> um.
> 
> I'm OK with merging patches and given lguest's newness, the timestamp on
> these patches, the fact that they don't change code generation (right?) and
> my reluctance to carry large do-nothing patches for two months, I'd be OK
> with squeaking them into 2.6.23.
> 
> But I worry that you're proposing adding what appears to be new
> Documentation-related machinery and infrastructure when there's already
> increased activity in that area from other people and we might all be
> headed in different directions and stuff.
> 
> So first I think we'd best form a kernel kommittee and mull this for a
> while (preferably months) to screw you around as much as poss, OK?  ;)
> 
> Items for consideration would be:
> 
> - if this stuff is good, shouldn't other code be using it?  If so, is
>   this new infrastructure in the correct place?

I wouldn't mind having a new doc infrastructure, but I don't see this as it.

> - if, otoh, this infrastructure is _not_ suitable for other code, well,
>   what was wrong with it?

I think that we don't want to give up html/pdf/ps output formats in
favor of just text or C source code.  If we do continue to have
multiple "rich" output formats, we need even more rich syntax rules
than we have right now.  OTOH, if we dump all of those rich output
formats, we have less tool spice that is needed.

(I'm not ignoring Andrew's question here.  I'm just applying the
7 patches/series and looking at it more.)

> - if the requirement is good, perhaps alternative implementations should
>   be explored (dunno what).

Yes, but I dunno what either.


> IOW, I'd be interested in hearing Rob and Randy's opinions on it all,
> please.

It's great that Rusty took the time to produce all of this documentation.
Few people do that today.

Were current kernel-doc tools not sufficient?  If not, why not?

---
~Randy
*** Remember to use Documentation/SubmitChecklist when testing your code ***