svn: /pear/peardoc/trunk/en/pyrus/ commands/generateext.xml developers/pear2.xml developers/pecl.xml

Modified: pear/peardoc/trunk/en/pyrus/commands/generateext.xml
===================================================================
--- pear/peardoc/trunk/en/pyrus/commands/generateext.xml	2009-08-06 03:16:05 UTC (rev 286861)
+++ pear/peardoc/trunk/en/pyrus/commands/generateext.xml	2009-08-06 03:18:49 UTC (rev 286862)
@@ -12,7 +12,7 @@
    be used to automatically update for a release.
   </para>
   <para>
-   One arguments is accepted, <literal>extension</literal>.
+   One argument is accepted, <literal>extension</literal>.
   </para>
   <para>
   This command automatically creates class definitions as well as ZEND_ARG_INFO
@@ -27,4 +27,173 @@
    used within files related to creating a PECL package.
   </para>
  </section>
+ <section xml:id="pyrus.commands.generateext.proto">
+  <title>--proto</title>
+  <para>
+   The <literal>--proto</literal> or <literal>-p</literal> option specifies a
+   file containing function and method prototypes to create in your new extension.
+  </para>
+  <para>
+   As an example, here are some supported protos:
+   <itemizedlist>
+    <listitem>
+     <simpara>
+      <literal>
+       int myfunc(string firstarg, unicode secondarg, array thirdarg,
+       object fourtharg [, double optionalarg1
+       [, float optionalarg2 [, callback optionalarg3 [, text optionalarg4]]]])
+      </literal>
+     </simpara>
+    </listitem>
+    <listitem>
+     <simpara>
+      <literal>
+       void Myclass::myfunc(array|object arg1, bool arg2, class arg3,
+       resource arg4, mixed arg5 [, ... varargs])
+      </literal>
+     </simpara>
+    </listitem>
+    <listitem>
+     <simpara>
+      <literal>
+       static int Myclass::staticfunc()
+      </literal>
+     </simpara>
+    </listitem>
+    <listitem>
+     <simpara>
+      <literal>
+       protected string Myclass::otherguy([mixed optionalarg])
+      </literal>
+     </simpara>
+    </listitem>
+    <listitem>
+     <simpara>
+      <literal>
+       static protected object Myclass::factory(text path)
+      </literal>
+     </simpara>
+    </listitem>
+   </itemizedlist>
+  </para>
+  <para>
+   A proto begins with either the return type or access modifiers
+   <literal>static</literal> and one of <literal>public</literal>,
+   <literal>protected</literal> and <literal>private</literal> followed
+   by the return type.  Next, the name of the function, or name of the
+   class::method is specified, followed by an argument list.  Optional
+   methods are enclosed in <literal>[brackets]</literal> and whitespace
+   is important, so follow the conventions as in the above examples.
+  </para>
+  <para>
+   Each argument consists of a type followed by an argument name.  The types are
+   informed by parameter parsing as supported by PHP's internal
+   <function>zend_parse_parameters</function>.  This is thoroughly documented
+   in the file <literal>README.PARAMETER_PARSING</literal> inside PHP's
+   source code.  Note that some of the parameter parsing choices only work
+   in PHP 6, in particular the unicode-related options.
+  </para>
+  <para>
+   The following types are supported:
+   <itemizedlist>
+    <listitem>
+     <simpara>
+      <literal>array</literal> (maps to <literal>'a'</literal> in parameter parsing)
+     </simpara>
+    </listitem>
+    <listitem>
+     <simpara>
+      <literal>array|object</literal> (maps to <literal>'A'</literal> in parameter parsing)
+     </simpara>
+    </listitem>
+    <listitem>
+     <simpara>
+      <literal>bool</literal> (maps to <literal>'b'</literal> in parameter parsing)
+     </simpara>
+    </listitem>
+    <listitem>
+     <simpara>
+      <literal>boolean</literal> (maps to <literal>'b'</literal> in parameter parsing)
+     </simpara>
+    </listitem>
+    <listitem>
+     <simpara>
+      <literal>callback</literal> (maps to <literal>'f'</literal> in parameter parsing)
+     </simpara>
+    </listitem>
+    <listitem>
+     <simpara>
+      <literal>class</literal> (Maps to <literal>'C'</literal> in parameter parsing)
+     </simpara>
+    </listitem>
+    <listitem>
+     <simpara>
+      <literal>double</literal> (maps to <literal>'d'</literal> in parameter parsing)
+     </simpara>
+    </listitem>
+    <listitem>
+     <simpara>
+      <literal>float</literal> (maps to <literal>'d'</literal> in parameter parsing)
+     </simpara>
+    </listitem>
+    <listitem>
+     <simpara>
+      <literal>handle</literal> (maps to <literal>'r'</literal> in parameter parsing)
+     </simpara>
+    </listitem>
+    <listitem>
+     <simpara>
+      <literal>int</literal> (Maps to <literal>'L'</literal> in parameter parsing)
+     </simpara>
+    </listitem>
+    <listitem>
+     <simpara>
+      <literal>long</literal> (Maps to <literal>'L'</literal> in parameter parsing)
+     </simpara>
+    </listitem>
+    <listitem>
+     <simpara>
+      <literal>mixed</literal> (maps to <literal>'z'</literal> in parameter parsing)
+     </simpara>
+    </listitem>
+    <listitem>
+     <simpara>
+      <literal>object</literal> (maps to <literal>'o'</literal> in parameter parsing)
+     </simpara>
+    </listitem>
+    <listitem>
+     <simpara>
+      <literal>resource</literal> (maps to <literal>'r'</literal> in parameter parsing)
+     </simpara>
+    </listitem>
+    <listitem>
+     <simpara>
+      <literal>string</literal> (maps to <literal>'s'</literal> in parameter parsing)
+     </simpara>
+    </listitem>
+    <listitem>
+     <simpara>
+      <literal>text</literal> (Maps to <literal>'T'</literal> in parameter parsing)
+     </simpara>
+    </listitem>
+    <listitem>
+     <simpara>
+      <literal>unicode</literal> (maps to <literal>'u'</literal> in parameter parsing)
+     </simpara>
+    </listitem>
+    <listitem>
+     <simpara>
+      <literal>void</literal>, use only for the return value of a function that returns nothing
+     </simpara>
+    </listitem>
+    <listitem>
+     <simpara>
+      <literal>...</literal> (varags: maps to <literal>'*'</literal> in parameter parsing)
+      However, if the parameter is not optional, if maps to <literal>'+'</literal>
+      is used.
+     </simpara>
+    </listitem>
+   </itemizedlist>
+  </para>
+ </section>
 </section>

Modified: pear/peardoc/trunk/en/pyrus/developers/pear2.xml
===================================================================
--- pear/peardoc/trunk/en/pyrus/developers/pear2.xml	2009-08-06 03:16:05 UTC (rev 286861)
+++ pear/peardoc/trunk/en/pyrus/developers/pear2.xml	2009-08-06 03:18:49 UTC (rev 286862)
@@ -13,5 +13,11 @@
   <para>
    <screen>php -dphar.readonly=0 pyrus.phar make -pphar,tar,tgz,zip</screen>
   </para>
+  <para>
+   In addition, Pyrus provides a simple facility for creating a new PEAR2 package,
+   the <link linkend="pyrus.commands.generatepear2">generate-pear2</link>
+   command.  With this command, a skeleton directory and file setup is created
+   that can be immediately used to get started with a new package.
+  </para>
  </section>
 </section>

Modified: pear/peardoc/trunk/en/pyrus/developers/pecl.xml
===================================================================
--- pear/peardoc/trunk/en/pyrus/developers/pecl.xml	2009-08-06 03:16:05 UTC (rev 286861)
+++ pear/peardoc/trunk/en/pyrus/developers/pecl.xml	2009-08-06 03:18:49 UTC (rev 286862)
@@ -26,14 +26,13 @@
  <section xml:id="pyrus.developers.pecl.newpackage">
   <title>Creating a new PECL package with Pyrus</title>
   <para>
-   If you are creating a brand new extension, after running a tool such as
-   <literal>ext_skel</literal> to set up the basic extension, a few extra
-   steps are needed to prepare the extension for installation by Pyrus or the
-   PEAR Installer.
+   If you are creating a brand new extension, you should use the
+   <link linkend="pyrus.commands.generateext">generate-ext</link>
+   command to create the basic structure of your extension.
   </para>
   <para>
-   When creating a new extension, first create a file named <literal>CREDITS</literal>
-   and put your information in the file like so:
+   After creating your extension, edit the newly-created <literal>CREDITS</literal>
+   file to have the correct information:
   </para>
 <screen>
  <![CDATA[
@@ -45,14 +44,14 @@
    Add any additional maintainers using the same format.
   </para>
   <para>
-   Next, create a <literal>README</literal> file that describes your package.
+   Next, edit the <literal>README</literal> file that describes your package.
    The first line should be a brief summary of what the extension does, and the
    rest of the file should be a detailed description of information the user
    should know about the origin of the extension, and perhaps a simple example
    of its usage.
   </para>
   <para>
-   Next, create a file named <literal>RELEASE-0.1.0</literal>.  Put any
+   Finally, edit the file named <literal>RELEASE-0.1.0</literal>.  Put any
    release notes in here.  Generally <literal>initial release</literal> is
    enough information for the first release.
   </para>
@@ -87,8 +86,8 @@
  <section xml:id="pyrus.developers.pecl.existingpackage">
   <title>Readying an existing PECL package for Pyrus</title>
   <para>
-   To prepare an existing PECL package for Pyrus, you should follow all of the
-   steps in the section
+   To prepare an existing PECL package for Pyrus, you should create all of the
+   information files described in the section
    <link linkend="pyrus.developers.pecl.newpackage">Creating a new PECL Package with Pyrus</link>,
    but instead of creating <literal>RELEASE-0.1.0</literal> and
    <literal>API-0.1.0</literal>, you would create a file named