# API2XML

#### 0.5.8

Current (0.5.8, unix)
Current (0.5.8, dos)

## Overview

### Abstract

API2XML is a documentation tool orthoganal to Java's javadoc tool. Thas is, API2XML extracts embedded sourcecode documentation and generates XML source, which can then be easily translated into HTML.

You can see an example of the end results at the REXML API Documentation page.

0.5.8: Better handling of events encountered outside of a class. Recursing into subdirectories never worked. Now it does.

0.5.7: Added class inheritance graphing. You can now abbreviate keywords; @param can be shortened to @p, @return to @r.

0.5.5: Includes weren't being written.

0.5.4: Have added hacks to avoid problematic situations. I'm starting to think that I'm going to have to implement a full Ruby interpreter just to parse source files :-/. In any case, Strings are the current problem; if you have a multi-line string, and the second line has the word "end" in it, you will confuse api2xml, and you'll start finding parts of the documantation for the API in random places.

### Introduction

Ruby already has RD, but I don't like RD. First, RD is dumb. I'm not saying that RD is a bad idea; I mean to say that RD itself doesn't help the documentor much -- RD documentation is just source comments with no contextual information drawn from the sourcecode. Second, RD uses the =begin...=end source documentation markup, which I find tedious; =begin and =end must start at the beginning of the line, and this disturbs my indentation; I just don't like it, aesthetically.

John Johnson has a priori written a utility called RubyDoc (curse his eyes!); you can find it at the RubyDoc homepage. Want to hear a funny story? I knew I had seen John's software, but when I went looking for it, I couldn't find it anywhere. So I wrote my own over the weekend. Then, come Monday, I went into my office and there on the computer was a copy of RubyDoc. That's a funny story! It is always funny when someone wastes four hours (or more!) of time on something that someone else has already written, like the Gnome people did with KDE. In any case, I found that RubyDoc wasn't exactly what I was looking for, so I continued to refine API2XML. I won't say which is better, but I like the fact that API2XML generates XML which can be styled. I don't like the fact that with API2XML you have to have an external XSLT processor, and there isn't a non-alpha one available for Ruby (at the moment).

API2XML uses the Ruby hash comments, and it interprets sourcecode to provide context for the comments, similar to javadoc. This relieves the programmer of some of the tedium of writing API documentation, which in turn makes it more likely that the programmer will actually write documentation.

I wrote this specifically for my REXML project, because I needed a way of nicely documenting the API for general consumption. If you use this, let me know, because I probably will only devote enough time to it to get it to meet my needs, otherwise.

### Features

- API2XML graphs your class inheritance hierarchy1.
- API2XML provides contextual information about the object being documented.
- For classes, the class name and the class it (optionally) extends are recorded, as well as attribute accessors, method aliases, includes, subclasses, and methods.
- For modules, the same objects as classes, as well as submodules.
- For methods, the arguments
- If you have Xalan installed, a script for generating HTML is provided
- Generated documentation is XML, so you can transform them with stylesheets. Some default stylesheets are provided.

## Operation

### Installation

There isn't much to install. You have to have REXML installed, or at least have the rexml directory in your Ruby include path, but other than that, just run the api2xml.rb application.

As of version 0.5.2, you no longer have to place the style sheets in the current directory when running transform.rb... IF you run it directly as a script, and not as an argument to the ruby command (IE, you run it with "translate.rb", not "ruby translate.rb"). For this to work, the stylesheets have to be in the same directory as the translate.rb executable. If you want to provide your own stylesheets, you can put them in the directory you call translate.rb from; they will override the default stylesheets. These stylesheets must be called, strangely enough, class.xsl and module.xsl.

If you really want some fancy API documentation, make sure you grab Robert Feldt's GraphR package2. If you do, you'll get a nice graphic class hierarchy diagram. API2XML will autodetect whether or not GraphR is installed (at runtime, not install time). If so, it will generate the inheritance graph, and link to it from the index.html file. At the moment, it generates Postscript, SVG, and PNG versions of the graph; only the Postscript is linked to3. If you want to see an example of this graph, here is the REXML graph.

### General Usage

API2XML recognizes comments on a number of objects. These objects are:

- classes
- modules
- method definitions (both class and module methods)
- attribute accessor variables
- aliased methods

In each of these cases, simply provide hash comments immediately preceeding the item to be documented. Blank lines may occur between the comments and the item, but no other code may. Comments may also occur at the end of a line, in which they will be included with any previous comments; comments after will not be included.

In the comments for method definitions, you can supply keywords. At the moment, the only keywords are @param and @return; they function like their JavaDoc equivalents.

keywords

    # Use this method to send a cow to Uzbekistan.
    # @param weight the weight of the cow to send, in pounds.
    # @return delivery confirmation, of class CowPie
    def send_cow_now( weight=1200 )
       # ...
    end

Once you've commented your code, run api2xml.rb and supply, as a command-line argument, the name of the directory that contains the sources. The script will make a directory called "api", and in that will mirror the directory structure of the directory you supplied on the command line.

    api2xml.rb rexml

In this case, my sources are in the directory "rexml". A directory called "api/rexml" will be created, with an XML document for every class and module in the ruby sources found in "rexml". Note that your sources must have the extension of ".rb" or ".ruby"; all other files are ignored.

Once done, you may transform the XML documents to HTML. If you have xalan installed, and a "xalan" executable in your path, you can use the transform.rb script to do this conversion for you.

    transform.rb

If you have another XSLT processor you want to use, edit the transform.rb script and change the processing command; it should be pretty easy to figure out.

Currently, you have to find your own entry point; there is no global index generated. Soon, young Jedi.

### Troubleshooting

The most common problem will be when you try to execute either api2xml.rb or transform.rb, and your shell tells you it can't find the command. The ruby executable normally lives in one of two places: /usr/local/bin or /usr/bin. If you compiled it yourself, it will probably be in /usr/local/bin. If you installed it with a RPM, it will probably be in /usr/bin. Change the first line of each script to point to the proper location of the ruby executable on your machine.

## Status

### Known Bugs

- If you have a source with method definitions that are contained in no class or method (IE, global methods), they are not handled properly, and will cause an exception.
- Your sources MUST be in a subdirectory!! Do NOT try and call "api2xml.rb .". If you do, I can't rule out any unpleasant side-effects, such as impotence or premature balding.
- You can confuse API2XML, probably pretty easily. Most of these cases can probably be fixed with some simple regexp tweaking, so please send me code snippets if you find something interesting.
- One guaranteed way to confuse API2XML is to define a multi-line string that has the word "end" in any line but the first.
- Uh, well, it isn't a bug, per se... but at the moment, all API2XML does is generate XML documents. I have supplied a little script that will style everything in a subdirectory for you using stylesheets, if you have xalan installed and in your $PATH. If you create any nice stylesheets, send them to me and I'll to them on this page.

### To Do

- Be smarter about formatting text. IE, insert a break for blank lines, turn columnar text into tables, etc. This from a discussion on ruby newsgroup, re: # # A class all about books # # Author: Jason Voegele # Version: 1.0 # # This class organizes books by # 1. Author # 2. Title # 3. Subject # # Its performance characteristics are as below: # # Num Books Processing Time (in secs) # 10 .001 # 100 .01 # 1000 100.5 # 10000 234,330,440.34 #
- Style sheets for plain text output.
- Link in to "ri", or something like ri. It is just too darned useful to ignore.
- Refactor. Simplify. Add documentation about how to extend.
- Unit tests. This could be difficult to measure, but they'll probably test counting "end"s
- Add links. These could occur anywhere in the documentation.
- Fix the graph output. Possibly have each class have a mini-graph of just its inheritance branch?4
- Constants
- Stylesheets
- Public/protected/private method handling5.
- Optionally tie into Ruby XSL processer, for Complete Solution
- Generate an index.
- Add framed stylesheets, so (optionally) output can be more like javadoc 1.1+
- Handle cases where the comment triggers are outside of a module or class context better (either ignore them, or add them to some default document)

## Credits

Here is a (probably) incomplete list of references and people that I have to thank for helping out with the project.

- The folks who invented JavaDoc (or the people they stole the idea from).
- Robert Feldt, for GraphR. This is a really nice, easy to use tool, and you should download and install it NOW! NOW!! DO IT NOW! No, really, you'll start finding all sorts of uses for graphs where you didn't see them before if you have this package, and Robert has been great about implementing features and bug fixes.

1) This feature requires Robert Feldt's most excellent GraphR package, which itself depends on GraphViz. Both of these are very easy to install. If you have an RPM based system, just grab the GraphViz RPM -- it works well. Links on the GraphR page.
2) You need at least version 0.1.3, or else API2XML won't work, and may bomb. You want 0.1.3 anyway; it is easier to use than the earlier versions.
3) I haven't yet figured out how, or even if it is possible, to change the rotation on the outputted graphs. At the moment, only the Postscript is correctly rotated; the SVG and PNG are improperly rotated.
4) This turned out to be less useful than I had imagined.
5) Right now, they are all handled the same way.