<!--
 RFC: Skeleton for php-doc-function.xml
 Version: 0.2
 State: Alpha
 Author: Philip Olson
 
 TODO:
 - Think other parts like class, method, predefined variables, constants, etc.
 - Discuss with multiple IDE developers, and ensure we include all desired information
 - Discuss handling of extensions with both OO and Procedural (ex: mysqli)
 - Discuss removing or adding elements, ex: add 'description' which might be the first paragraph of role=description?
 - Create a theme/format for PhD to generate this
 - Think about ways this could help find inconsistencies in the manual
 - Have methods for conversion into other forms like a sqlite db, funcindex.xml, quickref, ...
 - Discuss license issues for various uses like IDE integration
 - This deals with: http://bugs.php.net/bug.php?id=47651
 NOTES:
 - The current version (0.2) should not be taken too seriously -- it's a proof of concept
   Its intention is to maximize the available information by adding options for users. For
   example, it's likely an IDE developer will not want all of this information so they'll
   pull (and format) their desired elements accordingly.
-->
 
<function>
  <name>foobar</name>
  <version>PHP 3, 4, 5</version>
  <purpose>Checks the foo of a bar</purpose>
  <!-- Before going live, let's evaluate our current manual IDs and realize:
       - They should work forever 
       - They are consistent
       - We like them
       - Note: some are not lowercase, problem?
      Typically the following url works: php.net/manualid so php.net/function.foobar
  -->
  <manualid>function.foobar</manualid>
 
  <!-- This information comes from both the methodsynopsis and parameters role -->
  <params>
    <param>
      <name>foo</name>
      <type>string</type>
      <description>Used for this and that</description>
      <optional>false</optional>
    </param>
    <param>
      <name>bar</name>
      <type>integer</type>
      <description>Used for this and that</description>
      <optional>true</optional>
      <initializer>42</initializer>
    </param>
  </params>
 
  <!-- Type from methodsynopsis, description from return role -->
  <return>
    <type>string</type>
    <description>This and that</description>
  </return>
 
  <changelog>
    <entry>
      <version>4</version>
      <change>this and that changed</change>
    </entry>
    <entry>
      <version>5</version>
      <change>another change</change>
    </entry>
  </changelog>
 
  <!-- Discuss: we may or may not want to add examples.
       We don't always have a return, but sometimes via screen.
  -->
  <example>
    <title>foo() example</title>
    <language>PHP</language>
    <code>Not sure if we want this

  <return>42</return>
</example>

<!-- Most documents do not have this, but some do -->
<errors>
  <description>Other error conditions</description>
</errors>

<!-- There are several different types of notes, discuss -->
<notes>
  <note>
    <type>note</note>
    <description>This is needed</description>
  </note>
  <note>
    <type>caution</note>
    <description>be careful about</description>
  </note>
  <note>
    <type>warning</note>
    <description>watch out!</description>
  </note>
</notes>

<!-- Determine the handling of our different type of see also links.
     External:
     - Typically contain a link and descriptive text
     Internal:
     - Typically are a single element, ex: <function>foo</function> 
     - Sometimes include descriptive text, ex: the <link linkend="bar">bar chapter</link>
     - The 'purpose' of these are available in phd
-->
<seealso>
  <entry>
    <type>function</type>
    <name>baz</name>
    <description>purpose of baz</description>
  </entry>
  <entry>
    <type>unknown</type>
    <name>stuff within first link</name>
    <description>the entire text</description>
  </entry>
</seealso>

</function> </code>