Archive for the 'AS3' Category

Natural Docs with Flash

Jeff July 10th, 2008

Natural Docs is a great way to generate professional, inter-linked documentation on your code.  While it took me a bit of effort to set it up, there isn’t actually anything that is ‘installed’; you simply need to put  files in the right directories and point them to each other.  Hopefully this saves you some time.

  1. Download Natural Docs from here
  2. Unzip the directory to a folder on your C drive (i.e.:_NaturalDocs)
  3. Download ActiveState - ActivePerl from here (Click ‘Get ActivePerl’ on right side of screen, then ‘Download’)
  4. Running the install (I chose the .msi) will create a ‘Perl’ directory on your C drive
  5. Modify the NaturalDocs.bat file in your _NaturalDocs folder to point to your Perl directory. (this is line 15 of the file, replace ‘perl‘ with: 
      C:\Perl\bin\wperl.exe NaturalDocs %NaturalDocsParams%
  6. In your project folder where your code is, create the following folders:
    1. as (this is where your actionscript files will be)
    2. MyDocumentation (this is where your documentation will be generated)
    3. NaturalDocsProjectFolder (this is your Natural Docs ‘project directory’)
  7. Create a bat file (text file ending in .bat) in your Natural Docs directory called ‘GenDocsMyProject.bat’ (The following three lines all need to be on separate lines of your .bat file and the folders listed need to match those created in step 6).

    8. Syntax:

    @echo off
"C:\_NaturalDocs\NaturalDocs.bat" -i C:\Project\MyProject\as -o html C:\Projects\MyProject\MyDocumentation -p C:\Projects\<code>MyProject</code><code>\NaturalDocsProjectFolder
pause
</code>
  8. (This last step is optional) Create a shortcut to your .bat file in your project directory so that when you change your comments you can re-generate the documentation without needing to go to your Natural Docs directory and double clicking the .bat file.

You need to document your code in a specific way for Natural Docs to be able to generate documents from it.  See here. To generate your documentation, doubleclick the .bat file (or shortcut) each time you change your code comments.  There is a way to have the documentation run as a part of the build process but I have not figured that out yet.