<html>
<head>
<style><!--
body {background-color:#ffffff;}
.file {border:1px solid #eeeeee;margin-top:1em;margin-bottom:1em;}
.pathname {font-family:monospace; float:right;}
.fileheader {margin-bottom:.5em;}
.diff {margin:0;}
.tasklist {padding:4px;border:1px dashed #000000;margin-top:1em;}
.tasklist ul {margin-top:0;margin-bottom:0;}
tr.alt {background-color:#eeeeee}
#added {background-color:#ddffdd;}
#addedchars {background-color:#99ff99;font-weight:bolder;}
tr.alt #added {background-color:#ccf7cc;}
#removed {background-color:#ffdddd;}
#removedchars {background-color:#ff9999;font-weight:bolder;}
tr.alt #removed {background-color:#f7cccc;}
#info {color:#888888;}
#context {background-color:#eeeeee;}
td {padding-left:.3em;padding-right:.3em;}
tr.head {border-bottom-width:1px;border-bottom-style:solid;}
tr.head td {padding:0;padding-top:.2em;}
.task {background-color:#ffff00;}
.comment {padding:4px;border:1px dashed #000000;background-color:#ffffdd}
.error {color:red;}
hr {border-width:0px;height:2px;background:black;}
--></style>
</head>
<body>
<table cellspacing="0" cellpadding="0" border="0" rules="cols">
<tr class="head"><td colspan="4">Commit in <b><tt>trunk/as2api</tt></b><span id="info"> on MAIN</span></td></tr>
<tr><td><tt><a href="#file1">as2api-documentation.xml</a></tt></td><td align="right" id="added">+146</td><td align="right" id="removed">-10</td><td nowrap="nowrap" align="center"><a href="http://svn.badgers-in-foil.co.uk/viewcvs.cgi/as2api/trunk/as2api/as2api-documentation.xml?rev=233&content-type=text/vnd.viewcvs-markup">233</a> <a href="http://svn.badgers-in-foil.co.uk/viewcvs.cgi/as2api/trunk/as2api/as2api-documentation.xml.diff?r1=233&r2=234">-></a> <a href="http://svn.badgers-in-foil.co.uk/viewcvs.cgi/as2api/trunk/as2api/as2api-documentation.xml?rev=234&content-type=text/vnd.viewcvs-markup">234</a></td></tr>
</table>
<pre class="comment">
Further documentation
</pre>
<hr /><a name="file1" /><div class="file">
<span class="pathname"><a
href="http://svn.badgers-in-foil.co.uk/viewcvs.cgi/as2api/trunk">trunk</a>/<a
href="http://svn.badgers-in-foil.co.uk/viewcvs.cgi/as2api/trunk/as2api">as2api</a></span><br />
<div class="fileheader"><big><b>as2api-documentation.xml</b></big> <small id="info"><a href="http://svn.badgers-in-foil.co.uk/viewcvs.cgi/as2api/trunk/as2api/as2api-documentation.xml?rev=233&content-type=text/vnd.viewcvs-markup">233</a> <a href="http://svn.badgers-in-foil.co.uk/viewcvs.cgi/as2api/trunk/as2api/as2api-documentation.xml.diff?r1=233&r2=234">-></a> <a href="http://svn.badgers-in-foil.co.uk/viewcvs.cgi/as2api/trunk/as2api/as2api-documentation.xml?rev=234&content-type=text/vnd.viewcvs-markup">234</a></small></div>
<pre class="diff"><small id="info">--- trunk/as2api/as2api-documentation.xml 2005-08-14 00:47:14 UTC (rev 233)
+++ trunk/as2api/as2api-documentation.xml 2005-08-17 23:14:14 UTC (rev 234)
@@ -329,11 +329,114 @@
</small></pre><pre class="diff" id="context"> </section>
<section>
</pre><pre class="diff" id="removed">- <title>Syntax <span id="removedchars">Reference</span></title>
</pre><pre class="diff" id="added">+ <title>Syntax <span id="addedchars">Overview</span></title>
</pre><pre class="diff" id="context">
</pre><pre class="diff" id="removed">- <para><remark>TODO</remark></para>
</pre><pre class="diff" id="added">+ <para>The javadoc-style syntax supported by as2api allows the contents
+ of javadoc comments to contain special javadoc 'tags' to add extra
+ meaning, and XHTML tags if extra formatting (e.g. tabulated information)
+ is required.</para>
</pre><pre class="diff" id="context">
</pre><pre class="diff" id="added">+ <para>If the first non-whitespace characters on a line within a comment
+ are one or more asterisks (the '*' character), then everything upto and
+ including the initial asterisks on the line will be stripped before it
+ reaches the documentation. This allows you to use the common comment
+ formatting idiom whereby the left-hand margin of the comment is marked
+ with a column of asterisks.</para>
+
+ <example>
+ <title>Initial Asterisks on Comment Lines </title>
+
+ <screen>/**
+ * This is an
+ * example
+ */</screen>
+
+ <para>The documentation will include the text <quote>This is an
+ example</quote>; the '*' characters before the words
+ <wordasword>This</wordasword> and <wordasword>example</wordasword>
+ will disappear.</para>
+ </example>
+
+ <para>Javadoc tags appear in two forms, <wordasword>block</wordasword>
+ tags, such as <literal>@throws</literal>, and
+ <wordasword>inline</wordasword> tags, such as
+ <literal>{@link}</literal>.</para>
+
+ <para>Tags that are allowed in some contexts may not be allowed in
+ others. For instance <literal>@throws</literal> is allowed to appear
+ in the documentation of methods, but not in the documentation of
+ classes. See the Syntax Reference below for the full details.</para>
+
</pre><pre class="diff" id="context"> <section>
</pre><pre class="diff" id="added">+ <title>Block Tags</title>
+
+ <para>Documenation-comment is split into 'blocks'. The first block is
+ always a general description of the API element to which the comment is
+ attached. No special tag is required to denote this description block.
+ Further blocks are added to the comment with block-tags, which must
+ always appear at the beginning of a new line.</para>
+
+ <example>
+ <title>Valid Block-Tag Usage</title>
+ <screen>/**
+ * So then this is the
+ * description.
+ * @throws Error in all cases
+ */</screen>
+ </example>
+
+ <example>
+ <title>Invalid Block-Tag Usage</title>
+ <screen>/**
+ * So then this is the
+ * description. @throws Error in all cases
+ */</screen>
+ </example>
+
+ <example>
+ <title>Block-Tag With Newlines</title>
+ <screen>/**
+ * So then this is the
+ * description.
+ * @throws Error in all cases
+ *
+ * text appearing here is still part of the 'throws'
+ * block
+ */</screen>
+ </example>
+ </section>
+
+ <section>
+ <title>Inline Tags</title>
+
+ <para>Inline tags can appear within the middle of a line of comment
+ text (unlike block-tags, which must always appear at the start of a
+ line). Inline tags are always surrounded by curly braces (the '{' and
+ '}' characters) so that as2api can tell them appart from 'normal'
+ text.</para>
+ </section>
+
+ <section>
+ <title>XHTML Tags</title>
+
+ <example>
+ <title>XHTML Markup in Comments</title>
+ <screen><![CDATA[/**
+ * The allowed values are:
+ * <ul>
+ * <li>0.1</li>
+ * <li>0.01</li>
+ * <li>-6.66</li>
+ * </ul>
+ */]]></screen>
+ </example>
+ </section>
+ </section>
+
+ <section>
+ <title>Syntax Reference</title>
+
+ <section>
</pre><pre class="diff" id="context"> <title>Supported JavaDoc Features</title>
<informaltable>
</pre><pre class="diff"><small id="info">@@ -353,9 +456,9 @@
</small></pre><pre class="diff" id="context"> <entry>Describe a class or interface</entry>
</row>
<row>
</pre><pre class="diff" id="removed">- <entry><link linkend="method_description">Method
</pre><pre class="diff" id="added">+ <entry><link linkend="member_description">Member
</pre><pre class="diff" id="context"> Description</link></entry>
</pre><pre class="diff" id="removed">- <entry>Describe a method of a class or interface</entry>
</pre><pre class="diff" id="added">+ <entry>Describe a <span id="addedchars">field/</span>method of a class or interface</entry>
</pre><pre class="diff" id="context"> </row>
<row>
<entry><link linkend="param_tag"><literal>@param</literal></link></entry>
</pre><pre class="diff"><small id="info">@@ -518,13 +621,15 @@
</small></pre><pre class="diff" id="context"> </formalpara>
</section>
</pre><pre class="diff" id="removed">- <section id="method_description">
- <title>Method Description</title>
</pre><pre class="diff" id="added">+ <section id="member_description">
+ <title>Member Description</title>
</pre><pre class="diff" id="context">
</pre><pre class="diff" id="removed">- <para><remark>TODO</remark></para>
</pre><pre class="diff" id="added">+ <para>A doc-comment immediately before a method or field is used as
+ the description of that member. The text here will be added to this
+ members section in the type's API reference.</para>
</pre><pre class="diff" id="context">
<example>
</pre><pre class="diff" id="removed">- <title>Me<span id="removedchars">thod</span> Description</title>
</pre><pre class="diff" id="added">+ <title>Me<span id="addedchars">mber</span> Description</title>
</pre><pre class="diff" id="context"> <programlisting><emphasis role="strong">/**
* Clears all data that has previously been
* collected in this object, and returns it to
</pre><pre class="diff"><small id="info">@@ -538,6 +643,17 @@
</small></pre><pre class="diff" id="context"> }</programlisting>
</example>
</pre><pre class="diff" id="added">+ <para>When implicit fields are created (using
+ <literal>function get foo()</literal> or
+ <literal>function set foo()</literal> methods), an entry will be
+ created for this in the 'Fields' section of the resulting documentation
+ (not in the 'Methods' section). If both <literal>get</literal> and
+ <literal>set</literal> methods are defined for a field, as2api will
+ 'pick' the doc-comment from one of them to use as documentation for the
+ resulting field. If only one of <literal>get</literal> or
+ <literal>set</literal> are defined, the documentation will note
+ that the field is read-only or write-only, as appropriate.</para>
+
</pre><pre class="diff" id="context"> <formalpara>
<title>May contain</title>
<para><link linkend="param_tag">@param</link>, <link linkend="return_tag">@return</link>, <link linkend="see_tag">@see</link></para>
</pre><pre class="diff"><small id="info">@@ -547,8 +663,19 @@
</small></pre><pre class="diff" id="context"> <section id="param_tag">
<title>Method Parameters</title>
</pre><pre class="diff" id="removed">- <para><remark>TODO</remark></para>
</pre><pre class="diff" id="added">+ <para>Within the doc-comment describing a method,
+ <literal>@param</literal> tags may be used to give a description
+ for each of the method's parameters. Immidiately following the
+ <literal>@param</literal> must be the name of the parameter to
+ be described, with any text following this name being used as the
+ description.</para>
</pre><pre class="diff" id="context">
</pre><pre class="diff" id="added">+ <para>Arguments named in <literal>@param</literal> tags must match
+ the names of the actual method arguments, or they will be skipped.
+ The special parameter name '...' may be used if the method can
+ accept a variable number of paramters (by inspecting it's
+ <literal>arguments</literal> array.</para>
+
</pre><pre class="diff" id="context"> <example>
<title>Method Parameters</title>
<programlisting>/**
</pre><pre class="diff"><small id="info">@@ -565,6 +692,8 @@
</small></pre><pre class="diff" id="context"> * index of the current value (starting with
* 0 for the first value, 1 for the second,
* and so on).
</pre><pre class="diff" id="added">+ * <emphasis role="strong">@param ...</emphasis> any additional arguments to be passed
+ * to the callback function.
</pre><pre class="diff" id="context"> */
public function each(callback:Function,
index:Boolean):Void {
</pre><pre class="diff"><small id="info">@@ -576,11 +705,18 @@
</small></pre><pre class="diff" id="context"> <section id="return_tag">
<title>Method Return Values</title>
</pre><pre class="diff" id="removed">- <para><remark>TODO</remark></para>
</pre><pre class="diff" id="added">+ <para>A description of the value returned by a method, where the method
+ description itself does not give this information succinctly
+ enough.</para>
+
</pre><pre class="diff" id="context"> <example>
<title>Method Return Values</title>
<programlisting>/**
* Get the value corresponding to the given key
</pre><pre class="diff" id="added">+ * by searching in the local cache first, then
+ * in the database on the LAN, and finally
+ * consulting a number of LDAP servers from
+ * around the wider internet.
</pre><pre class="diff" id="context"> *
* <emphasis role="strong">@return</emphasis> either the value for the given key, or
* null if there is no such mapping.
</pre></div>
<center><small><a href="http://www.badgers-in-foil.co.uk/projects/cvsspam/" title="commit -> email">CVSspam</a> 0.2.11</small></center>
</body></html>