<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;}
#copied {background-color:#ccccff;}
tr.alt #copied {background-color:#bbbbf7;}
#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 {white-space:-moz-pre-wrap;white-space:-pre-wrap;white-space:-o-pre-wrap;white-space:pre-wrap;word-wrap:break-word;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="5">Commit in <b><tt>as2api/trunk/as2api</tt></b></td></tr>
<tr><td><tt><a href="#file1">as2api-documentation.xml</a></tt> </td><td></td><td align="right" id="added">+115</td><td align="right" id="removed">-1</td><td nowrap="nowrap" align="center">323 -> 324</td></tr>
</table>
<pre class="comment">
Beginnings of documentation for API-changes mode
</pre>
<hr /><a name="file1" /><div class="file">
<span class="pathname">as2api/trunk/as2api</span><br />
<div class="fileheader"><big><b>as2api-documentation.xml</b></big> <small id="info">323 -> 324</small></div>
<pre class="diff"><small id="info">--- trunk/as2api/as2api-documentation.xml 2006-03-22 20:47:49 UTC (rev 323)
+++ trunk/as2api/as2api-documentation.xml 2006-03-22 23:46:36 UTC (rev 324)
@@ -7,7 +7,7 @@
</small></pre><pre class="diff" id="context"> <!ATTLIST titleabbrev id ID #IMPLIED>
]>
</pre><pre class="diff" id="removed">-<?xml-stylesheet href="/home/dave/projects/<span id="removedchars">docbook/</span>css/xml/docbook/driver.css"
</pre><pre class="diff" id="added">+<?xml-stylesheet href="/home/dave/projects/css/xml/docbook/driver.css"
</pre><pre class="diff" id="context"> type="text/css"?>
</pre><pre class="diff"><small id="info">@@ -70,8 +70,18 @@
</small></pre><pre class="diff" id="context"> <arg>--draw-diagrams</arg>
<arg>--dot-exe <replaceable>executable-path-and-name</replaceable></arg>
<arg>--sources</arg>
</pre><pre class="diff" id="added">+ <arg>--api-export</arg>
+ <arg>--api-name <replaceable>text</replaceable></arg>
+ <arg>--api-version <replaceable>text</replaceable></arg>
</pre><pre class="diff" id="context"> <arg rep="repeat" choice="plain"><replaceable>package-spec</replaceable></arg>
</cmdsynopsis>
</pre><pre class="diff" id="added">+ <cmdsynopsis>
+ <command>as2api</command>
+ <arg choice="plain">--diff-load-old <replaceable>file.xml</replaceable></arg>
+ <arg choice="plain">--diff-load-new <replaceable>file.xml</replaceable></arg>
+ <arg>--diff-url-old <replaceable>DocsURL</replaceable></arg>
+ <arg>--diff-url-new <replaceable>DocsURL</replaceable></arg>
+ </cmdsynopsis>
</pre><pre class="diff" id="context"> </refsynopsisdiv>
<refsection id="options">
</pre><pre class="diff"><small id="info">@@ -217,6 +227,49 @@
</small></pre><pre class="diff" id="context"> converted to an HTML file with 'syntax highlighting'.</para>
</listitem>
</varlistentry>
</pre><pre class="diff" id="added">+
+ <varlistentry>
+ <term><option>--api-export</option></term>
+ <listitem>
+ <para>Causes as2api to export the API description as a single
+ XML document, rather than the normal set of HTML files. This
+ file is for use with the <option>--diff-load-old</option> and
+ <option>--diff-load-new</option> options.</para>
+ <para>If this option is used, the <option>--api-name</option> and
+ <option>--api-version</option> options become mandatory, and
+ their values are used to determine the name of the XML file that
+ will be produced.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--api-name <replaceable>text</replaceable></option></term>
+ <listitem>
+ <para>A short name for the ActionScript API being
+ processed.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--api-version <replaceable>text</replaceable></option></term>
+ <listitem>
+ <para>A value identifting the version of the API being processed,
+ to differentiate it from other versions of the same API. This
+ free-form value may be a version number, release date, CVS tag,
+ etc.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--diff-load-old <replaceable>oldfile.xml</replaceable></option> / <option>--diff-load-new <replaceable>newfile.xml</replaceable></option></term>
+ <listitem>
+ <para>When this pair of options are supplied, as2api doesn't
+ generate any API documentation, instead, the two versions of the
+ API described by <replaceable>oldfile.xml</replaceable> and
+ <replaceable>newfile.xml</replaceable> are examined, and a
+ report is produced describing how the API has changed.</para>
+ </listitem>
+ </varlistentry>
</pre><pre class="diff" id="context"> </variablelist>
</refsection>
</refentry>
</pre><pre class="diff"><small id="info">@@ -853,4 +906,65 @@
</small></pre><pre class="diff" id="context"> </section>
</section>
</pre><pre class="diff" id="added">+ <section>
+ <title>Advanced Usage</title>
+
+ <section>
+ <title>API 'Diffs'</title>
+
+ <para>This feature of as2api is inspired by the
+ <ulink url="http://www.jdiff.org/">JDiff</ulink> tool for JavaDoc.</para>
+
+ <para>as2api has a special mode of operation in which it doesn't document
+ an API, but rather it documents the differences between two versions of
+ the same API.</para>
+
+ <para>These reports allow the user's of an API to focus attention on the
+ important features when learning about a new release. They could also
+ be used by the API developer to check for backwards-incompatable
+ changes.</para>
+
+ <para>Since parsing ActionScript code is a somewhat expensive operation,
+ as2api doesn't use the original code as the basis for comparison.
+ Instead, it first dumps a description of the API to an XML file, and
+ then given two dump-files, it can report the differences between
+ them.</para>
+
+ <para>As an example, we will generate a report of the differences between
+ the core classes in Flash 7 and Flash 8.</para>
+
+ <example>
+ <title>Generating API Dump Files</title>
+
+ <para>Dump the Flash 7 API description to a file called
+ <filename>flash_core_classes-7.xml</filename>,</para>
+
+ <screen>as2api --api-export \
+ --classpath examples/flash8/FP7 \
+ --api-name "Flash Core Classes" \
+ --api-version 7 \
+ "(default)" "System" "TextField"</screen>
+
+ <para>Dump the Flash 8 API description to a file called
+ <filename>flash_core_classes-8.xml</filename>,</para>
+
+ <screen>as2api --api-export \
+ --classpath examples/flash8/FP8 \
+ --api-name "Flash Core Classes" \
+ --api-version 8 \
+ "(default)" "System" "TextField" "flash.*"</screen>
+ </example>
+
+ <para>With two API dump files, we are now in a position to generate the
+ report describing the changes.</para>
+
+ <example>
+ <title>Generating an API-Change Report</title>
+
+ <para>Creates a report starting at <filename>apidoc/changes/change-summary.html</filename></para>
+ <screen>as2api --diff-load-old flash_core_classes-7.xml \
+ --diff-load-new flash_core_classes-8.xml</screen>
+ </example>
+ </section>
+ </section>
</pre><pre class="diff" id="context"> </article>
</pre></div>
<center><small><a href="http://www.badgers-in-foil.co.uk/projects/cvsspam/" title="commit -> email">CVSspam</a> 0.2.12</small></center>
</body></html>