Documentation updates

Signed-off-by: Lanny McNie <[email protected]>

Author: Lanny McNie

src/soundjs/FlashPlugin.js

@@ -43,7 +43,7 @@ this.createjs = this.createjs || {};
 	 * {{#crossLink "Sound"}}{{/crossLink}} using the {{#crossLink "Sound/registerPlugins"}}{{/crossLink}} method. This
 	 * plugin is recommended to be included if sound support is required in older browsers such as IE8.
 	 *
-	 * This plugin requires FlashAudioPlugin.swf and swfObject.js (which is compiled
+	 * This plugin requires FlashAudioPlugin.swf and swfObject.js, which is compiled
 	 * into the minified FlashPlugin-X.X.X.min.js file. You must ensure that {{#crossLink "FlashPlugin/swfPath:property"}}{{/crossLink}}
 	 * is set when using this plugin, so that the script can find the swf.
 	 *
@@ -56,10 +56,10 @@ this.createjs = this.createjs || {};
 	 * will have an id of "flashAudioContainer". The container DIV is positioned 1 pixel off-screen to the left to avoid
 	 * showing the 1x1 pixel white square.
 	 *
-	 * <h4>Known Browser and OS issues for HTML Audio</h4>
+	 * <h4>Known Browser and OS issues for Flash Audio</h4>
 	 * <b>All browsers</b><br />
 	 * <ul><li> There can be a delay in flash player starting playback of audio.  This has been most noticeable in Firefox.
-	 * Unfortunely this is an issue with the flash player and therefore cannot be addressed by SoundJS.</li></ul>
+	 * Unfortunely this is an issue with the flash player and the browser and therefore cannot be addressed by SoundJS.</li></ul>
 	 *
 	 * @class FlashPlugin
 	 * @constructor
@@ -71,22 +71,23 @@ this.createjs = this.createjs || {};
 	var s = FlashPlugin;
 
 	/**
-	 * The capabilities of the plugin. This is generated via the {{#crossLink "WebAudioPlugin/generateCapabilities"}}{{/crossLink}}
+	 * The capabilities of the plugin. This is generated via the {{#crossLink "WebAudioPlugin/_generateCapabilities"}}{{/crossLink}}
 	 * method. Please see the Sound {{#crossLink "Sound/getCapabilities"}}{{/crossLink}} method for a list of available
 	 * capabilities.
 	 * @property capabilities
 	 * @type {Object}
+	 * @protected
 	 * @static
 	 */
 	s.capabilities = null;
 
 	/**
 	 * Deprecated in favor of {{#crossLink "FlashPlugin/swfPath:property"}}{{/crossLink}}
-	 * The path relative to the HTML page that the FlashAudioPlugin.swf resides. Note if this is not correct, this
+	 * <br />The path relative to the HTML page that the FlashAudioPlugin.swf resides. Note if this is not correct, this
 	 * plugin will not work.
 	 * @property BASE_PATH
 	 * @type {String}
-	 * @default src/SoundJS
+	 * @default null
 	 * @static
 	 * @deprecated
 	 */
@@ -515,7 +516,8 @@ this.createjs = this.createjs || {};
 		},
 
 // Flash Communication
-		/**
+// Note we have decided not to include these in the docs
+		/*
 		 * Used to couple a Flash loader instance with a <code>Loader</code> instance
 		 * @method registerPreloadInstance
 		 * @param {String} flashId Used to identify the Loader.
@@ -525,7 +527,7 @@ this.createjs = this.createjs || {};
 			this.flashPreloadInstances[flashId] = instance;
 		},
 
-		/**
+		/*
 		 * Used to decouple a <code>Loader</code> instance from Flash.
 		 * @method unregisterPreloadInstance
 		 * @param {String} flashId Used to identify the Loader.
@@ -534,7 +536,7 @@ this.createjs = this.createjs || {};
 			delete this.flashPreloadInstances[flashId];
 		},
 
-		/**
+		/*
 		 * Used to couple a Flash sound instance with a {{#crossLink "SoundInstance"}}{{/crossLink}}.
 		 * @method registerSoundInstance
 		 * @param {String} flashId Used to identify the SoundInstance.
@@ -544,7 +546,7 @@ this.createjs = this.createjs || {};
 			this.flashInstances[flashId] = instance;
 		},
 
-		/**
+		/*
 		 * Used to decouple a {{#crossLink "SoundInstance"}}{{/crossLink}} from Flash.
 		 * instance.
 		 * @method unregisterSoundInstance
@@ -555,7 +557,7 @@ this.createjs = this.createjs || {};
 			delete this.flashInstances[flashId];
 		},
 
-		/**
+		/*
 		 * Used to output traces from Flash to the console, if {{#crossLink "FlashPlugin/showOutput"}}{{/crossLink}} is
 		 * <code>true</code>.
 		 * @method flashLog
@@ -568,7 +570,7 @@ this.createjs = this.createjs || {};
 			}
 		},
 
-		/**
+		/*
 		 * Handles events from Flash, and routes communication to a {{#crossLink "SoundInstance"}}{{/crossLink}} via
 		 * the Flash ID. The method and arguments from Flash are run directly on the sound instance.
 		 * @method handleSoundEvent
@@ -594,7 +596,7 @@ this.createjs = this.createjs || {};
 			}
 		},
 
-		/**
+		/*
 		 * Handles events from Flash and routes communication to a <code>Loader</code> via the Flash ID. The method
 		 * and arguments from Flash are run directly on the sound loader.
 		 * @method handlePreloadEvent
@@ -620,7 +622,7 @@ this.createjs = this.createjs || {};
 			}
 		},
 
-		/**
+		/*
 		 * Handles events from Flash intended for the FlashPlugin class. Currently only a "ready" event is processed.
 		 * @method handleEvent
 		 * @param {String} method Indicates the method to run.
@@ -635,7 +637,7 @@ this.createjs = this.createjs || {};
 			}
 		},
 
-		/**
+		/*
 		 * Handles error events from Flash. Note this function currently does not process any events.
 		 * @method handleErrorEvent
 		 * @param {String} error Indicates the error.

src/soundjs/HTMLAudioPlugin.js

@@ -47,7 +47,7 @@ this.createjs = this.createjs || {};
 	 * <b>All browsers</b><br />
 	 * Testing has shown in all browsers there is a limit to how many audio tag instances you are allowed.  If you exceed
 	 * this limit, you can expect to see unpredictable results.  This will be seen as soon as you register sounds, as
-	 * tags are precreated to all Chrome to load them.  Please use {{#crossLink "Sound.MAX_INSTANCES"}}{{/crossLink}} as
+	 * tags are precreated to allow Chrome to load them.  Please use {{#crossLink "Sound.MAX_INSTANCES"}}{{/crossLink}} as
 	 * a guide to how many total audio tags you can safely use in all browsers.
 	 *
      * <b>IE 9 html limitations</b><br />
@@ -63,15 +63,19 @@ this.createjs = this.createjs || {};
 	 * <ul><li>Safari requires Quicktime to be installed for audio playback.</li></ul>
 	 *
 	 * <b>iOS 6 limitations</b><br />
-	 * Note it is recommended to use {{#crossLink "WebAudioPlugin"}}{{/crossLink}} for iOS (6+). HTML Audio is disabled by
-	 * default as it can only have one &lt;audio&gt; tag, can not preload or autoplay the audio, can not cache the audio,
-	 * and can not play the audio except inside a user initiated event.
-	 *<br /><br />
-	 * <b>Android HTML Audio limitations</b><br />
+	 * <ul><li>Note it is recommended to use {{#crossLink "WebAudioPlugin"}}{{/crossLink}} for iOS (6+)</li>
+	 * 		<li>HTML Audio is disabled by default because</li>
+	 * 		<li>can only have one &lt;audio&gt; tag</li>
+	 * 		<li>can not preload or autoplay the audio</li>
+	 * 		<li>can not cache the audio</li>
+	 * 		<li>can not play the audio except inside a user initiated event.</li>
+	 * </ul>
+	 *
+	 * <b>Android Native Browser limitations</b><br />
 	 * <ul><li>We have no control over audio volume. Only the user can set volume on their device.</li>
-	 *      <li>We can only play audio inside a user event (touch/click).  This currently means you cannot loop sound or use a delay.</li>
+	 *      <li>We can only play audio inside a user event (touch/click).  This currently means you cannot loop sound or use a delay.</li></ul>
 	 * <b> Android Chrome 26.0.1410.58 specific limitations</b><br />
-	 * 		<li>Chrome reports true when you run createjs.Sound.BrowserDetect.isChrome, but is a different browser
+	 * <ul><li>Chrome reports true when you run createjs.Sound.BrowserDetect.isChrome, but is a different browser
 	 *      with different abilities.</li>
 	 *      <li>Can only play 1 sound at a time.</li>
 	 *      <li>Sound is not cached.</li>
@@ -117,6 +121,7 @@ this.createjs = this.createjs || {};
 	 * @type {String}
 	 * @default canplaythrough
 	 * @static
+	 * @protected
 	 */
 	s.AUDIO_READY = "canplaythrough";
 
@@ -126,6 +131,7 @@ this.createjs = this.createjs || {};
 	 * @type {String}
 	 * @default ended
 	 * @static
+	 * @protected
 	 */
 	s.AUDIO_ENDED = "ended";
 
@@ -135,15 +141,17 @@ this.createjs = this.createjs || {};
 	 * @type {String}
 	 * @default seeked
 	 * @static
+	 * @protected
 	 */
 	s.AUDIO_SEEKED = "seeked";
 
 	/**
 	 * Event constant for the "error" event for cleaner code.
 	 * @property AUDIO_ERROR
 	 * @type {String}
-	 * @default error
+	 * @default stalled
 	 * @static
+	 * @protected
 	 */
 	s.AUDIO_ERROR = "error"; //TODO: Handle error cases
 
@@ -269,7 +277,7 @@ this.createjs = this.createjs || {};
 	/**
 	 * Pre-register a sound instance when preloading/setup. This is called by {{#crossLink "Sound"}}{{/crossLink}}.
 	 * Note that this provides an object containing a tag used for preloading purposes, which
-	 * <a href="http://preloadjs.com">PreloadJS</a> can use to assist with preloading.
+	 * <a href="http://preloadjs.com" target="_blank">PreloadJS</a> can use to assist with preloading.
 	 * @method register
 	 * @param {String} src The source of the audio
 	 * @param {Number} instances The number of concurrently playing instances to allow for the channel at any time.
@@ -306,12 +314,15 @@ this.createjs = this.createjs || {};
 		};
 	};
 
+	// TODO remove this when | approach is removed
 	/**
+	 * Deprecated as this will not be required with new approach to basePath.
 	 * Checks if src was changed on tag used to create instances in TagPool before loading
 	 * Currently PreloadJS does this when a basePath is set, so we are replicating that behavior for internal preloading.
 	 * @method handleTagLoad
 	 * @param event
 	 * @protected
+	 * @deprecated
 	 */
 	p.handleTagLoad = function(event) {
 		// cleanup and so we don't send the event more than once