xml-dev - Re: XML language for Software documentation?

[tpassin@home.com]

Lisa Retief asked -
>
> We (my software development team) are entering an intensive documenting
> phase of a project, and I am trying to access whether there is an existing
> markup language that we could use. Doing it in anything other than XML
makes
> no sense to me.
>
> Does anyone have experience or thoughts in this area? Do you know of
> existing resources? The development language is Java - javadocs are cool
but
> is there a way to integrate with XML?
>
Python has pythondoc, which does something similar to javadoc.  pythondoc
has an optional xml output.  I don't know if there is a DTD, but I've
attached an xml file it produced for a file fft.py that i ran it on.  Looks
like a good starting point, anyway.

Tom Passin
<?xml version="1.0"?>

<!-- Generated by pythondoc.XMLFormatter 0.7 -->


<Module id="fft">
<Function id="fft.bitrev">
<Arguments>
<Argument id="x"></Argument>
</Arguments>

<Description>
<P>Return bit-reversed list, whose length is assumed to be 2^n:
eg. 0111 &lt;--&gt; 1110 for N=2^4.</P>
</Description>
</Function>

<Function id="fft.fft">
<Arguments>
<Argument id="x"></Argument>

<Argument id="sign">
<Default>-1</Default>
</Argument>
</Arguments>

<Description>
<P>
FFT using Cooley-Tukey algorithm where N = 2^n.  The choice of
e^{-j2\pi/N} or e^{j2\pi/N} is made by 
<Code>sign=-1</Code>
 or 
<Code>sign=1</Code>

respectively.  Since I prefer Engineering convention, I chose

<Code>sign=-1</Code>
 as the default.</P>

<P>FFT is performed as follows:
1. bit-reverse the array.
2. partition the data into group of m = 2, 4, 8, ..., N data points.
3. for each group with m data points,
    1. divide into upper half (section A) and lower half (section B),
        each containing m/2 data points.
    2. divide unit circle by m.
    3. apply "butterfly" operation 
            |a| = |1  w||a|	or	a, b = a+w*b, a-w*b
            |b|   |1 -w||b|
        where a and b are data points of section A and B starting from
        the top of each section, and w is data points along the unit
        circle starting from z = 1+0j.
FFT ends after applying "butterfly" operation on the entire data array
as whole, when m = N.
</P>
</Description>
</Function>

<Function id="fft.ifft">
<Arguments>
<Argument id="X"></Argument>
</Arguments>

<Description>
<P>
Inverse FFT with normalization by N, so that x == ifft(fft(x)) within
round-off errors.
</P>
</Description>
</Function>

<Function id="fft.nextpow2">
<Arguments>
<Argument id="i"></Argument>
</Arguments>

<Oneliner>Find 2^n that is equal to or greater than.</Oneliner>
</Function>

<Variable id="fft.__file__" type="string">
<Value>'.\\fft\\fft.py'</Value>
</Variable>

<Variable id="fft.e" type="float">
<Value>2.71828182846</Value>
</Variable>

<Variable id="fft.pi" type="float">
<Value>3.14159265359</Value>
</Variable>

<Description>
<P>fft routines from Simple Recipes in Python by William Park, March 1999.
Reads a single-column file of time-domain floating-point data.  Number of 
data points must be an exact power of 2.  Discards comment lines (lines which
don't convert to a number) and blank lines.</P>

<P>fft returns a real fft as a file of single-column floating-point numbers.
No amplitude normalization convention has been applied.</P>

<P>8-15-2000 Adapted by Thomas B. Passin.
</P>
</Description>
</Module>