At 01:16 PM 9/24/2001 +0100, Dave Mitchell wrote:
>Dan Sugalski <[EMAIL PROTECTED]> wrote:
> > Subject: What should and shouldn't get documented?
> >
> > I see there's a lot of embedded documentation going into the core, and
> > that's a good thing. That brings up a question, though--what exactly
> should
> > we document, and where should it be seen?
> >
> > For an example, the opcode functions should *never* be used outside the
> > interpreter core itself, but documenting them's still a good thing.
> >
> > Maybe we need a way to tag the type of documentation for each
> function--the
> > module it belongs to and how exposed it should be, or something.
>
>Well, we already tag the api it belongs to. It stikes me that exposure
>can be one or more of:
>
>1. internal to the subsystem
>2. usable by the whole core
>3. usable by extensions
>4. usable by embedders
>
>I'm not sure if (3) and (4) need to be distingished. Also, I'm not sure
>whether (2) needs to be further subdivided, eg into parrot and perl/python/...
3 and 4 need distinguishing, but there will be *very* few routines in 4. If
we have more than 8, I think we have too many. (Though I may change my mind
at some point)
Dan
--------------------------------------"it's like this"-------------------
Dan Sugalski even samurai
[EMAIL PROTECTED] have teddy bears and even
teddy bears get drunk
