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/...
We could have some flag letters following the API name, eg
/*=for api string IC ....
- exposed internally to itself (I) and to the core (C).
Something exposed to extensions need not necessarily be I or C.
The same flags could also be used for auto-header generation.
Should we go the full hog and make the /*=for api ... */ bit in the
src field subsume any info we currently append to embed.pl etc in Perl 5?
