The Macromedia Flash Docs are utterly reprehensible!!!

I've been a Flash developer for over 9 years now and throughout that time, I have longed for acceptable documentation from Macromedia. Each new version of Flash adds a myriad of poorly documented features while generally failing to improve the documentation on existing functions. I will now provide a perfect example of what I mean. The (relatively) new v2 component architecture specifies that you should not set the depth of new component instances the way you used to using getNextHighestDepth(), but instead should rely on the new DepthManager class to instantiate and manage components on the stage. Well, here are the docs that explain that. We will assume for the moment that you actually managed to find the Macromedia Component Language Reference after your failed expedition to the regular Actionscript Reference. After finding the docs for the DepthManager class and then stumbling upon the actual function you need to use, you would finally end up at this page:

http://livedocs.macromedia.com/flash/mx2004
/main_7_2/wwhelp/wwhimpl/common/html/wwhelp.htm?context=Flash_MX_2004&file=00002429.html


Which gives this information....

DepthManager.createClassChildAtDepth()
Availability
Flash Player 6 (6.0.79.0).

Edition
Flash MX 2004.

Usage
movieClipInstance.createClassChildAtDepth(className, depthFlag[, initObj])


Parameters
className A class name. This parameter is a of type Function.

depthFlag One of the following values: DepthManager.kTop, DepthManager.kBottom, DepthManager.kTopmost, DepthManager.kNotopmost. All depth flags are static properties of the DepthManger class. You must either reference the DepthManager package (for example, mx.managers.DepthManager.kTopmost), or use the import statement to import the DepthManager package.

initObj An initialization object. This parameter is optional.

Returns
A reference to the created child. The return type is UIObject.

Description
Method; creates a child of the class specified by className at the depth specified by depthFlag.

Example
The following code draws a focus rectangle in front of all NoTopmost objects:

import mx.managers.DepthManager
this.ring = createClassChildAtDepth(mx.skins.RectBorder, DepthManager.kTop);


The following code creates an instance of the Button class and passes it a value for its label property as an initObj parameter:

import mx.managers.DepthManager
button1 = createClassChildAtDepth(mx.controls.Button, DepthManager.kTop, {label: "Top Button"});

The first example they give, isn't even testable without first creating a bunch of other code. And if you are dumb enough to try the second example, you'll quickly see that it DOESN'T FUCKING WORK! In fact, it's so far off base, that I spent an ENTIRE FUCKING WEEKEND trying to get it to work as documented. Rest assured it does not.

Now please visit my post on Flashkit.com to see how it is acutally done:
http://board.flashkit.com/board/showthread.php?t=702902



So you can hopefully see now, why it has taken me 3 days to display a progress bar and then destroy it when I'm done with it.

Adobe has a major problem on its hands with these docs. As Actionscript 2 is now evolving into Actionscript 3 with different flavors for Flash 9, Flex, Flashlite, etc... it is going to become increasingly impossible to code actionscript. Adobe should fucking drop whatever they are doing on the development side and put 100% of their efforts into fixing the doc system before writing another line of code. I honestly can't believe they've made something so simple into such a complicated mess. What the fuck is wrong with a single centralized HTML-based documentation system like PHP uses? Instead of spending hours combing through one of 4 different language references depending on whether you're looking for component docs, or core docs, or remoting docs, etc.....why can't I just go to a fucking web page with the name of the function I'm looking for and get ALL the docs related to it? Imagine a world where you could go to http://www.adobe.com/actionscript/createclasschildatdepth and actually find what you are looking for along with actual working examples contributed by users? When was the last time you found something useful in the Macromedia user comments on a specific doc page? More often than not there are NO comments whatsoever. This is why I can write a complete application in PHP in a day and the same application takes me a month to do in Flash. It's absolutely pathetic and unforgivable. Is anyone at MM/Adobe listening? Have they ever tried to use their own software? I can't say enough bad things about the Actionscript docs, so I won't continue this tirade. I just wish they'd hire someone that knew what they were doing and didn't treat the act of finding a function reference so much like a god damned treasure hunt!