Access key module

[Grzegorz Nosek]

On Mon, Dec 31, 2007 at 03:47:13PM +0100, Manlio Perillo wrote:
> Grzegorz Nosek ha scritto:

> >I'm not going to fight about putting them in a single tree (though I'd
> >like it), but I think they should all be accessible from a single place
> >with a unified interface. IMO this makes them look more polished than a
> >bunch of links (an svn here, a tarball there etc.). However, this would
> >require a certain amount of coordination between module authors.
> >
> 
> Keeping all in a single tree can be a good thing, but it will need a 
> rethink about how each developer handle its module.

Well, the modules might be in separate trees but should present a single
interface for browsing, download, documentation and reporting bugs. This
will be rather simple when all developers agree on a single RCS system,
set up some bridge between them or hell freezes over ;)

Maybe we should choose an RCS that maybe even nobody uses personally,
but has a decent web interface and can import/export repositories to all
common systems.

What I'm aiming for (I guess) is a central place for nginx third-party
modules, with one-click download of the whole pack, maybe some
coordinated release schedule etc.

> >I think that documenting headers is less useful than the bigger picture.
> >This is IMHO a major deficiency in many OSS projects, which document
> >every class/function via doxygen and call it a day. E.g. to use shared
> >memory in nginx, you need not only to allocate a segment and use it, but
> >also wire it up in such a way that subsequent reloads don't trash it
> >or cause leaks etc. Even the best documentation for a single function
> >won't cut it (again, IMHO). I'd like the documentation to be
> >task-oriented, i.e. "How do I write a handler?", "When and how should I
> >use rbtrees?", etc. It could then serve as a sequel to the Guide.
> >
> 
> But I don't want to just write reference documentation.
> I want to use a bottom-up method, starting with documenting each header 
> files, and then integrating all the documentation.
> 
> This is, IMHO, more easy.

It seems I misunderstood you. I thought you want to just document the
API. IMO a top-down approach is more informative. The low-level details
can be quickly found by reading the source, while the big picture
requires more time to "sink in".

Of course, as this is all OSS, the worst that happens if we disagree is
that we end up meeting in the middle ;)

Best regards,
 Grzegorz Nosek