TITLE

Documenting PMCs

Overview

This document describes guidelines for writing documentation for PMCs. All core PMCs must be documented using the format outlined here. We encourage other PMC developers to follow these practices, too.

Follow all documentation guidelines in docs/pdds/pdd07_codingstd.pod.

NAME

Required. Specify the filename relative to the Parrot root, followed by a brief description of the PMC's intent.

 =head1 NAME

 src/pmc/exporter.pmc - Export globals from one namespace to another

DESCRIPTION

Required. A verbose description of the PMC's intent, mentioning the major use cases. Include links to spec/design documentation or other related files. Describe the interface (what this PMC inherits from, and what interfaces it provides) -- a description of the information contained in the pmclass declaration.

 =head1 DESCRIPTION

 Exports globals from one namespace to another. Exporter always uses
 the typed namespace interface, as outlined in
 F<docs/pdds/pdd21_namespaces.pod>.

 Exporter is not derived from any other PMC, and does not provide any
 standard interface--its interface consists solely of non-vtable methods.

The DESCRIPTION section is further broken down as follows:

Structure

Describe the underlying structure of the PMC. Often this information has been contained in source comments. It should be formalized and made available to others by converting it to POD. Mention initialization and finalization behavior.

 =head2 Structure

 The Exporter PMC structure (C<Parrot_Exporter>) consists of three items:

 =over 4

 =item C<ns_src>

 The source namespace -- a NameSpace PMC.
 An empty PMC of this type is allocated upon initialization.

 =item C<ns_dest>

 The destination namespace -- a NameSpace PMC.
 An empty PMC of this type is allocated upon initialization.

 =item C<globals>

 The globals to export -- a ResizableStringArray.
 A Null PMC is allocated during initialization.

Functions

Required. Group all PMC functions together in the source, and describe them individually.

 =head2 Functions

 =over 4

 =item C<void init()>

 Instantiates an Exporter.

etc.

Methods

Required. Group all PMC methods together (VTABLE or otherwise,) and describe function, expected parameters, and return values.

 =head2 Methods

 =over 4

 =item C<PCCMETHOD
 import(PMC *dest :optional :named["destination"], int got_dest :opt_flag,
 PMC *src :optional :named["source"], int got_src :opt_flag,
 PMC *globals :optional :named["globals"], int got_globals :opt_flag)>

 Import C<globals> from the C<src> namespace to the C<dest> namespace.
 If C<src>, C<dest>, or C<globals> are passed, they will override
 the current value.
 C<import> follows the semantics of the C<export_to> method
 of the C<NameSpace> PMC. in particular, if a NULL value is passed
 for C<globals>, the default set of items will be imported.
 Throws an exception upon error.

STABILITY

Required. List the stability of this PMC, as classified in docs/stability.pod.

SEE ALSO

Recommended. List related documentation.

 =head1 SEE ALSO

 F<docs/pdds/pdd17_basic_types.pod>, F<docs/pdds/pdd21_namespaces.pod>.

STABILITY

Unstable. This is a draft document, which must be reviewed and accepted by the Project Team.