javadoc/doxygen/autodoc ... for Io? (not c!)

[Bart Botma]

Hi,

Doxygen does not support the Io language. Writing a parser for Io and
adding it to the doxygen sources is hard (well, it looks difficult to me).

Does anyone have something similar as javadoc/doxygen/... suitable for
the Io language?

Currently, I am writing Io code with @class,@method,@see etc in the
source comments, but I lack a tool to create a meaningful
cross-reference (nice html?) output.

Any ideas?
Bart

[Michael Witten]

On 7 Jun 2008, at 4:16 AM, Bart Botma wrote:

> Does anyone have something similar as javadoc/doxygen/... suitable for
> the Io language?

Literate Programming perhaps: http://www.eecs.harvard.edu/~nr/noweb/

Maybe something like: http://www.cims.nyu.edu/~dbindel/eigenstuff/2007-04.html

[Steve Dekorte]

On 2008-06-07, at 1:16 AM, Bart Botma wrote:

> Doxygen does not support the Io language. Writing a parser for Io and
> adding it to the doxygen sources is hard (well, it looks difficult  
> to me).
>
> Does anyone have something similar as javadoc/doxygen/... suitable for
> the Io language?
>
> Currently, I am writing Io code with @class,@method,@see etc in the
> source comments, but I lack a tool to create a meaningful
> cross-reference (nice html?) output.

Io has a build in documentation system. If you look at the Io's C or  
Io source code you'll find comments like these in IoImage.c:

//metadoc Image copyright Steve Dekorte, 2004
//metadoc Image license BSD revised
//metadoc Image category Graphics
/*metadoc Image description
The Image object can read and draw images and provide the image
data as a buffer. Example use;
<pre>
image = Image clone open("curly.png")
image draw
image scaleTo(image width / 2, image height / 2)
image save("curly.tiff")
</pre>
When loading an attempt will be made to convert the image into whichever
of the following formats it is closest to: L8, LA8, RGB8, RGBA8.
<p>
Currently supported formats include PNG(which supports alpha), JPG and  
TIFF.
*/


and then for methods, comments like this one:

        /*doc Image setDataWidthHeightComponentCount(aSequence, width,  
height, componentCount)
        Sets the image data and it's parameters. Returns self.
        */

If your code has comments like this and you run "make doc", it will  
auto build the docs/IoReference.html file.

[Bart Botma]

Thanks Steve.

I will look into it. Actually, what started my quest was something
that would help me with requirement traceability, and not specifically
cross references. I like my method to "claim" certain requirements and
comment in the code where those requirements end up.

Example:
/*****************************************************************************\
 * #Interface create(#String)
 *
 * Clones the #Interface, and sets the physical device interface
 * name. Creates a concrete #Interface if the parent is abstract.
 *
 * Note:
 *  - Auto installs itself in the current #Network, but
 *    only if the physical device interface name is set.
 *  - If the #Interface is abstract, all #Interface properties
 *    must be copied to the clone.
 *
 * @param     Physical device interface name as #String
 * @return    #Interface
 * @exception #Error
 *
 * Claims [REQ.A.INTERFACE:{CREATE,NAME}],
 *        [REQ.I.INTERFACE:INSTALL]
\*****************************************************************************/

create := method(s_name,
 # --- sanity check [REQ.S.SANITY]
 ERROR_IF_NIL(s_name,
  "physical device name is missing with interface")
 ERROR_IF(self my_b_alive and (nil != self name),
  "already initialized interface " .. self name)
 # --- create object [REQ.A.INTERFACE:CREATE]
 o_self := self dup
 o_self my_b_alive = true
 o_self my_l_tail = o_self
 o_self my_o_super = call sender
 # --- dup abstract interface [REQ.A.INTERFACE:CLONE]
 if (nil == self name) then (
  o_self my_l_filters = self my_l_filters clone
  o_self my_l_subnets = self my_l_subnets clone
  o_self my_l_relays  = self my_l_relays  clone
 )
 # --- set name [REQ.A.INTERFACE:NAME]
 o_self name(s_name)
 ERROR_IF_NOT(o_self name isExtIdentifier,
  "name " .. o_self name .. " is not a valid interface name")
 # --- install into the network [REQ.I.INTERFACE:INSTALL]
 o_self my_o_super install(o_self)
 return o_self
)

As you can see, the comments contain references to requirements that I
would like to trace at the file level, but also at the project level
(to check for coverage).

Doxygen does not support this, but I was hoping I could mold it into
something that would work for me. Unfortunately, doxygen does not
support other languages very well.

But I will look into the documentation system of Io itself. I probably
also have to change the parser to scan comments.

Regards,
Bart

--- In iolanguage@..., Steve Dekorte <steve@...> wrote:

>
>
> On 2008-06-07, at 1:16 AM, Bart Botma wrote:
> > Doxygen does not support the Io language. Writing a parser for Io and
> > adding it to the doxygen sources is hard (well, it looks difficult  
> > to me).
> >
> > Does anyone have something similar as javadoc/doxygen/... suitable for
> > the Io language?
> >
> > Currently, I am writing Io code with @class,@method,@see etc in the
> > source comments, but I lack a tool to create a meaningful
> > cross-reference (nice html?) output.
>
> Io has a build in documentation system. If you look at the Io's C or  
> Io source code you'll find comments like these in IoImage.c:
>
> //metadoc Image copyright Steve Dekorte, 2004
> //metadoc Image license BSD revised
> //metadoc Image category Graphics
> /*metadoc Image description
> The Image object can read and draw images and provide the image
> data as a buffer. Example use;
> <pre>
> image = Image clone open("curly.png")
> image draw
> image scaleTo(image width / 2, image height / 2)
> image save("curly.tiff")
> </pre>
> When loading an attempt will be made to convert the image into whichever
> of the following formats it is closest to: L8, LA8, RGB8, RGBA8.
> <p>
> Currently supported formats include PNG(which supports alpha), JPG and  
> TIFF.
> */
>
>
> and then for methods, comments like this one:
>
> /*doc Image setDataWidthHeightComponentCount(aSequence, width,  
> height, componentCount)
> Sets the image data and it's parameters. Returns self.
> */
>
> If your code has comments like this and you run "make doc", it will  
> auto build the docs/IoReference.html file.
>