[Gd-chatter] r11084 - in trunk/documentation: gwydion topic/reference/lib/collections topic/reference/lib/collections/table-extensions

[agent at gwydiondylan.org]

Author: agent
Date: Wed Dec 20 08:58:30 2006
New Revision: 11084

Added:
   trunk/documentation/topic/reference/lib/collections/table-extensions/table.xml   (contents, props changed)
Modified:
   trunk/documentation/gwydion/gdlibs.sgml
   trunk/documentation/topic/reference/lib/collections/table-extensions.xml
Log:
Bug: 7339
FD and OD DITA documentation for table macro.



Modified: trunk/documentation/gwydion/gdlibs.sgml
==============================================================================
--- trunk/documentation/gwydion/gdlibs.sgml	(original)
+++ trunk/documentation/gwydion/gdlibs.sgml	Wed Dec 20 08:58:30 2006
@@ -5699,6 +5699,53 @@
   	your own table classes.
       </para>
   
+      <dylanmacrodef>
+    <defname> table </defname>
+    <defsummary>
+      Constructs an instance of <dname> &lt;table&gt; </dname> or a subclass.
+    </defsummary>
+    <defparameters>
+      <param>
+        <paramname> table-class </paramname>
+        <paramtype> &lt;mutable-collection&gt; </paramtype>
+      </param>
+      <param>
+        <paramname> key </paramname>
+        <paramtype> &lt;object&gt; </paramtype>
+      </param>
+      <param>
+        <paramname> value </paramname>
+        <paramtype> &lt;object&gt; </paramtype>
+      </param>
+    </defparameters>
+    <defdescription>
+      <para>
+        <dname> table </dname> is a function macro that instantiates and
+        populates a table, analogous to <dname> vector </dname> and
+        <dname> list </dname>. It may take two forms:
+        <programlisting>
+table(table-class, key => value, ...)
+table(key => value, ...)
+</programlisting>
+        The former returns an instance of <parameter>table-class</parameter>,
+        while the latter returns an instance of <dclass> &lt;table&gt;
+        </dclass>, or more properly, a concrete subclass of
+        <dclass> &lt;table&gt; </dclass>.
+      </para>
+      <para>
+        Although intended for tables, any instance of <dclass>
+        &lt;mutable-collection&gt; </dclass> may be used for
+        <parameter>table-class</parameter>.
+      </para>
+      <para>
+        An example of the usage of <dname> table </dname>:
+        <programlisting>
+let lights = table(&lt;string-table&gt;, "red" => "stop", "green" => "go");
+</programlisting>
+      </para>
+    </defdescription>
+      </dylanmacrodef>
+    
       <dylanclassdef>
   	<defname> &lt;case-insensitive-string-table&gt; </defname>
   	<defadjectives>

Modified: trunk/documentation/topic/reference/lib/collections/table-extensions.xml
==============================================================================
--- trunk/documentation/topic/reference/lib/collections/table-extensions.xml	(original)
+++ trunk/documentation/topic/reference/lib/collections/table-extensions.xml	Wed Dec 20 08:58:30 2006
@@ -25,6 +25,9 @@
     <link href="../common-dylan/common-extensions/Lstring_tableG.xml">
       <linktext><apiname>&lt;string-table&gt;</apiname></linktext>
     </link>
+    <link href="table-extensions/table.xml">
+      <linktext><apiname>table</apiname></linktext>
+    </link>
     <link href="table-extensions/case_insensitive_equal.xml">
       <linktext><apiname>case-insensitive-equal</apiname></linktext>
     </link>

Added: trunk/documentation/topic/reference/lib/collections/table-extensions/table.xml
==============================================================================
--- (empty file)
+++ trunk/documentation/topic/reference/lib/collections/table-extensions/table.xml	Wed Dec 20 08:58:30 2006
@@ -0,0 +1,57 @@
+<?xml version='1.0' encoding='UTF-8'?>
+<!DOCTYPE dylanMacro PUBLIC "-//Gwydion//DTD DITA Dylan API Macro//EN" "../../../../dtd/dylanMacro.dtd" []>
+<dylanMacro id="lib-collections-table-extensions-table">
+  <apiName>table</apiName>
+
+  <shortdesc>Constructs a table.</shortdesc>
+
+  <prolog>
+    <author>Dustin Voss</author>
+    <copyright>
+      <copyryear year="2006"/>
+      <copyrholder>Gwydion Dylan Maintainers</copyrholder>
+    </copyright>
+  </prolog>
+
+  <dylanMacroDetail>
+    <apiSyntax>
+      <apiSyntaxText>
+        table(<apiItemName>table-class</apiItemName>, <apiItemName>key</apiItemName> => <apiItemName>value</apiItemName>, ...)
+        table(<apiItemName>key</apiItemName> => <apiItemName>value</apiItemName>, ...)
+      </apiSyntaxText>
+      <apiSyntaxItem>
+        <apiItemName>table-class</apiItemName>
+        <apiDefNote>The type of the table.</apiDefNote>
+      </apiSyntaxItem>
+      <apiSyntaxItem>
+        <apiItemName>key</apiItemName>
+        <apiDefNote>The key to associate with a collection element.</apiDefNote>
+      </apiSyntaxItem>
+      <apiSyntaxItem>
+        <apiItemName>value</apiItemName>
+        <apiDefNote>An element of the collection.</apiDefNote>
+      </apiSyntaxItem>
+    </apiSyntax>
+
+    <apiDesc>
+      <p>Instantiates and populates a table, analogous to
+      <apioperation href="../../dylan/dylan/vector.xml">vector</apioperation>
+      and <apioperation href="../../dylan/dylan/list.xml">list</apioperation>.
+      An invocation of this macro may take two forms. The first form returns
+      an instance of <parmname>table-class</parmname>, while the second form
+      returns an instance of <apiclassifier
+      href="../../dylan/dylan/LtableG.xml">&lt;table&gt;</apiclassifier>, or
+      more properly, a concrete subclass of <apiclassifier
+      href="../../dylan/dylan/LtableG.xml">&lt;table&gt;</apiclassifier>.</p>
+      
+      <p>Although intended for tables, any instance of <apiclassifier
+      href="../../dylan/dylan/Lmutable-collectionG.xml">
+      &lt;mutable-collection&gt;</apiclassifier> may be used for <parmname>
+      table-class</parmname>.</p>
+    </apiDesc>
+    
+    <example>
+let lights = table(&lt;string-table&gt;, "red" => "stop", "green" => "go");
+</example>
+  </dylanMacroDetail>
+</dylanMacro>