docs/pmc/documentation.pod - Documenting PMCs.
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.
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
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
=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 methods, not vtable functions.
The DESCRIPTION section is further broken down as follows:
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.
Required. Group all PMC functions together in the source, and describe them individually.
=head2 Functions =over 4 =item C<void init()> Instantiates an Exporter.
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.
Required. List the stability of this PMC, as classified in docs/stability.pod.
Recommended. List related documentation.
=head1 SEE ALSO F<docs/pdds/pdd17_basic_types.pod>, F<docs/pdds/pdd21_namespaces.pod>.
Unstable. This is a draft document, which must be reviewed and accepted by the Project Team.