With the launch of our new website, this site, myflashlab.com, I tried to help users use our classes with a better expirience and that was when I thought of generating adobe like AS API documentations!
to tell you the truth, at first I did not know that there’s a tool to automatically generate these nice looking documents! so the first document I generated was done totally manually with my DreamWeaver! it took a lot of time, there were so many broken links between the pages and it finally gave me a feeling that made me say, how crazy adobe is to be building these documents!
After being almost disappinted, I noticed that some open source programmes like paperVision or some other have the very same looking documentations! so I was suspisous that there must be a tool for doing this time consuming work and I was right, there is a nice tool and it’s called asDoc generator 
In this post I will talk about my own expiriences on how I managed to generate the documentations I needed for my classes. there may be better approaches that I’m not aware of. but this is what is working for me and I am happy with. If you have a better idea or something, please share it with us.
I presume that you have built all your project and you have all your .as files ready and you just want to generate the asDoc. the very first thing you must notice is that in your .as files, when you are writting your classes, you must respect some commenting rules. you need to write comments in a special way so the generator would be able to nicely relate the comments to the appropriate property or method in your class. the best book I’ve seen to give you all the rules is the one adobe has, read it here http://blogs.adobe.com/flexdoc/pdfs/asdoc.pdf
ok, now that you have your .as files ready and with a correct kind of commenting rules, you are ready to generate your documents, download the flex sdk from this page: http://opensource.adobe.com/wiki/display/flexsdk/Downloads
the latest SDK I downloaded once was flex_sdk_3.3.0.4852 and it is still working fine for me. (works fine for player 9 projects only! read this post here if you are trying to generate asDoc for a project in player 10)
extract your SDK to your computer, I have put it here in my xp (C:\Program Files\Adobe\flex_sdk_3.3.0.4852\)
now open your note pad and all you have to do is to copy the below string! and change it to your suite. I will explain what they mean:
C:\Program Files\Adobe\flex_sdk_3.3.0.4852\bin\asdoc.exe >> This is the path to the generator tool, change the path as it is in your computer.
-output “G:\project\classes\bg\doc” >> This is the address of the folder where the generated html files will be saved to.
-main-title “MyFlashLab AS3 Components language reference” >> This is the main title of the documentation files.
-window-title “MyFlashLab” -footer “www.myFlashLab.com – December 16, 2009″ >> These are the window title and the footer for your documents.
-source-path “G:\project\as” >> This is the path to your classes. ok, be careful about this one so I’ll explain a bit more, you probably are using different open source or classes you may have purchased from here and there, and you yourself are most probably saving your .as files in a location like com.yourSite.classes.Class right? so, the source path is the address where you have placed your “com” folder…
-doc-classes com.doitflash.utils.bg.Bg com.doitflash.utils.bg.BgConst com.doitflash.utils.bg.BgType >> This is where you put all the classes you want to generate the documentations for.
-exclude-dependencies=true >> This will make sure that the generator is not generating documentations for other classes being imported into your main classes, setting this to true will make sure that the generator will only generate documentations for the mentioned classes and nothing more.
After putting this string into your notepad, save the file not in .txt extension but in .bat extension! and then just execute that .bat file and you will see the black msDoc window open doing some works… if it finishes it work after some seconds, depending on the amount of your classes, you can go to the folder where you outputed the files and there they are, you are done run the index.html to see the homepage for your asDoc files.
the very exact above code, generated these documents here for me: http://myflashlab.com/documentation/AS3/com/doitflash/utils/bg/
Personally, I enjoyed how easy generating asDoc was but I posted this artical anyway because I couldn’t find one easy artical explaining all the steps. so I thought, that would be a good idea if I do it
Regards,
Hadi
