NaturalDocs: Documenting ActionScript in Linux and Windows

In my view when it comes to documenting Actionscript, nothing comes close to NaturalDocs. Its a point and shoot procedure and words cannot express the admiration I have for the work Greg Valure has done on this amazing tool. I've tried a few other documentation tools and this one comes tops all the time. The most impressive feature of this documentation tool is the way it sets up the sub and super classes of the target class so you can trace its hierachy should you need to do so. The downside is that it is a command line tool by default and having being brought up on Windows I have never been one to enjoy command line tools. This malady is cured by the tool that a dear friend Richard Leggett had written for poor souls like myself in mind - NaturalGUI. I have not been able to work it in Ubuntu but for Windows its brilliant. Still, the NaturalDocs command line is extremely easy to deploy so I have not felt the pinch.

You can find enough documentation on formating and syntax and all that in the very well documented NaturalDocs help. What in my view was lacking was a how to get started. I hope this little bijou I'm offering here will fill that gap.

Linux: The distro I use is Ubuntu 8.04 so its the process of starting NaturalDOcs in this distro I will be using to explain the Linux procedure. I'm a new emigree to Ubuntu so, for hardened users if I make descriptive errors I beg pardon.

  1. Download the NauralDocs zip archive and unzip to a folder you create called NaturalDocs in the /home/[user name] folder.
  2. Open your terminal and change directory (cd) to /home/[user name]/NaturalDocs
  3. chmod +x NaturalDocs (this is crucial, Ubuntu does not give write permissions by default so if you do not do this it will not work).
  4. Now point NaturalDocs at the folder you want to document. -i means input folder, -o means output, -p means project folder.

ayo@cyclone:~$ ./NaturalDocs -i /media/disk/Mortar/aYo/ -o HTML /media/disk/Mortar/aYo/docs -p /media/disk/Mortar/MLP/aYo/docs

Voila, your documentation appears.

Windows: Windows follows the exact same procedure but, there is an added step in theinitial set up - PERL. You need to install PERL on your computer as NaturalDocs is a Perl script. You also do not need to chmod NaturalDocs in Windows. In the Windows environment, Richard Leggett's GUI comes into play beautifully. Unzip it into the NaturalDocs folder, run it, place the folder paths in the form fields and click the 'Generate' button. That's it, documentation created.

aYo Binitie II

No comments: