docs/pmc/documentation.pod

   1 =head1 TITLE
   2
   3 Documenting PMCs
   4
   5 =head1 Overview
   6
   7 This document describes guidelines for writing documentation for PMCs.
   8 All core PMCs B<must> be documented using the format outlined here.
   9 We encourage other PMC developers to follow these practices, too.
  10
  11 Follow all documentation guidelines in F<docs/pdds/pdd07_codingstd.pod>.
  12
  13 =over
  14
  15 =item NAME
  16
  17 Required. Specify the filename relative to the Parrot root, followed by
  18 a brief description of the PMC's intent.
  19
  20  =head1 NAME
  21
  22  src/pmc/exporter.pmc - Export globals from one namespace to another
  23
  24 =item DESCRIPTION
  25
  26 Required. A verbose description of the PMC's intent, mentioning the major
  27 use cases. Include links to spec/design documentation or other related
  28 files. Describe the interface (what this PMC inherits from, and what
  29 interfaces it provides) -- a description of the information contained
  30 in the C<pmclass> declaration.
  31
  32  =head1 DESCRIPTION
  33
  34  Exports globals from one namespace to another. Exporter always uses
  35  the typed namespace interface, as outlined in
  36  F<docs/pdds/pdd21_namespaces.pod>.
  37
  38  Exporter is not derived from any other PMC, and does not provide any
  39  standard interface--its interface consists solely of methods, not
  40  vtable functions.
  41
  42 The B<DESCRIPTION> section is further broken down as follows:
  43
  44 =over 4
  45
  46 =item Structure
  47
  48 Describe the underlying structure of the PMC. Often this information
  49 has been contained in source comments. It should be formalized and made
  50 available to others by converting it to POD. Mention initialization and
  51 finalization behavior.
  52
  53  =head2 Structure
  54
  55  The Exporter PMC structure (C<Parrot_Exporter>) consists of three items:
  56
  57  =over 4
  58
  59  =item C<ns_src>
  60
  61  The source namespace -- a NameSpace PMC.
  62  An empty PMC of this type is allocated upon initialization.
  63
  64  =item C<ns_dest>
  65
  66  The destination namespace -- a NameSpace PMC.
  67  An empty PMC of this type is allocated upon initialization.
  68
  69  =item C<globals>
  70
  71  The globals to export -- a ResizableStringArray.
  72  A Null PMC is allocated during initialization.
  73
  74 =item Functions
  75
  76 Required. Group all PMC functions together in the source, and describe them
  77 individually.
  78
  79  =head2 Functions
  80
  81  =over 4
  82
  83  =item C<void init()>
  84
  85  Instantiates an Exporter.
  86
  87 etc.
  88
  89 =item Methods
  90
  91 Required. Group all PMC methods together (VTABLE or otherwise,)
  92 and describe function, expected parameters, and return values.
  93
  94  =head2 Methods
  95
  96  =over 4
  97
  98  =item C<PCCMETHOD
  99  import(PMC *dest :optional :named["destination"], int got_dest :opt_flag,
 100  PMC *src :optional :named["source"], int got_src :opt_flag,
 101  PMC *globals :optional :named["globals"], int got_globals :opt_flag)>
 102
 103  Import C<globals> from the C<src> namespace to the C<dest> namespace.
 104  If C<src>, C<dest>, or C<globals> are passed, they will override
 105  the current value.
 106  C<import> follows the semantics of the C<export_to> method
 107  of the C<NameSpace> PMC. in particular, if a NULL value is passed
 108  for C<globals>, the default set of items will be imported.
 109  Throws an exception upon error.
 110
 111 =back
 112
 113 =item STABILITY
 114
 115 Required. List the stability of this PMC, as classified in
 116 F<docs/stability.pod>.
 117
 118 =item SEE ALSO
 119
 120 Recommended. List related documentation.
 121
 122  =head1 SEE ALSO
 123
 124  F<docs/pdds/pdd17_basic_types.pod>, F<docs/pdds/pdd21_namespaces.pod>.
 125
 126 =back
 127
 128 =head1 STABILITY
 129
 130 Unstable. This is a draft document, which must be reviewed and accepted by the Project Team.
 131
 132 =cut
 133