Merge pull request #1 from rwldrn/edits

Edits to core docs

effects/_posts/2012-12-12-applyclass.md

@@ -2,11 +2,11 @@
 
 ## Purpose ##
 
-Apply css class to jquery selector. Selector is relative to plugin target's id
+Apply a class by CSS Selector. Selector is relative to plugin target's `id`
 
 ## Options ##
 
-* **class** - specifies the class to apply to the plugin container, can be seperated by spaces for more then one class
+* `**class**` - specifies the class to apply to the plugin container, can be seperated by spaces for more then one class
 
 ## Examples ##
 

getting-started/_posts/2012-12-12-gettingstarted.md

@@ -1,6 +1,6 @@
 # Getting Started #
 
-We urge the video community, Javascript developers, and film makers alike to get involved and help with development in order to ensure an easy to use and adaptable library. There are many ways one can get involved; some include critiquing current work, filling out tickets/bugs, requesting additional functionality, spreading the word, and helping with documentation. Included below are ways to keep track of popcorn.js.
+The Popcorn.js development team wants to encourage the video and media community, JavaScript developers, and film makers alike to get involved and help with development in order to ensure an easy to use and adaptable library. There are many ways one can get involved, including: creating new projects and demos, critiquing current work, filing tickets/bugs, requesting additional functionality, spreading the word, and helping with documentation.
 
 ## Download Source ##
 

instance-methods/_posts/2012-12-12-autoplay.md

@@ -2,15 +2,15 @@
 
 ## Purpose ##
 
-autoplay is a Popcorn instance method, defined as a passthrough accessor to the HTMLMediaElement prototype property of the same name.  autoplay is used set the video automatically play if it is set to true.
+`autoplay()` is defined as a passthrough accessor to the HTMLMediaElement property of the same name. Use `autoplay( flag )` to set the media to automatically play when loaded.
 
 ## Options ##
 
-* **flag** - boolean value specifying whether the video should autoplay or not
+* `**flag**` - boolean value, when set to `true` will automatically play the media once it is loaded. When set to `false`, the media will not play until the `play()` method is called, or the user clicks the "play" button on the media player interface.
 
 ## Use Cases ##
 
-* Begin playing the video as soon as it is able to
+* Begin playing the media as soon as it is able to. This can also be achieved by calling `play()` once the media has loaded.
 
 ## Examples ##
 

instance-methods/_posts/2012-12-12-compose.md

@@ -2,13 +2,15 @@
 
 ## Purpose ##
 
-compose, which is also known as effects, works very similar to a traditional Popcorn.js plugin.  We create start and end functions as we would in a typical plugin and add an appropriate effect that will be triggered in each block.  Typically this means add an effect on start and remove it on end, but is in no way limited to this.  Compose creates the huge potential for css transitions between Popcorn events and really adds another depth to the users web made movie experience. compose is not limited to effects tho, and can be used for many other things as well.  Keep in mind that plugins events will be fired first and then any composed events will be fired after.
+`compose` provides the base logic for effects and works similarly to a traditional Popcorn.js plugin. Create `start` and `end` functions as you would in a typical plugin and add an appropriate effect that will be triggered in each block. Typically this means add an effect on `start` and remove it on `end`, but is in no way limited to this. Compose creates the huge potential for CSS transitions between Popcorn events and depth to the user's experience. `compose` is not limited to effects.
+
+Plugins events will be fired first, followed by composed events.
 
 ## Options ##
 
-* **name** - a string of the given name for the compose plugin
-* **definitionObject** -  is an object literal containing typical plugin methods ( setup, start, end ) where the compose logic will live
-* **manifest** - an optional manifest can be included
+* `**name**` - a string of the given name for the compose plugin
+* `**definitionObject**` -  is an object literal containing typical plugin methods ( setup, start, end ) where the compose logic will live
+* `**manifest**` - an optional manifest can be included
 
 ## Use Cases ##
 

instance-methods/_posts/2012-12-12-cue.md

@@ -2,12 +2,14 @@
 
 ## Purpose ##
 
-cue is an alias to exec(), meaning it provides the same functionality but is simply accessed through a seperate function name.  Cue was created with film makers in mind by using a familiar keyword in order to make developing Popcorn.js projects simpler.
+`cue()` is a preferred alias to `exec()`.
+
+`cue()` was created with film makers in mind by using a familiar keyword in order to make developing Popcorn.js projects simpler.
 
 ## Options ##
 
-* **time** - the time in which the cue will be fired at
-* **callback** - a callback function that will be executed at a given **time** in a cue
+* `**time**` - number of seconds or SMPTE format string. The time in which the cue will be fired at
+* `**callback**` - callback. Function to execute at the given `**time**`
 
 ## Use Cases ##
 

instance-methods/_posts/2012-12-12-currenttime.md

@@ -1,12 +1,13 @@
-# currentTime #
+# currentTime( [time] ) #
 
 ## Purpose ##
 
 Set or Get the Popcorn video object instance currentTime
 
 ## Options ##
 
-* **seconds** - if seconds exists, we are setting the currentTime ( go to that time in the video ), and if it is not present, we are returning what the currentTime is
+* `**time**` - number of seconds or SMPTE format string. If a `time` parameter is passed, set the media's current time to this value. If no `time` parameter, return the value of the `currentTime` property in seconds.
+
 
 ## Use Case ##
 

instance-methods/_posts/2012-12-12-defaults.md

@@ -1,15 +1,15 @@
-# defaults #
+# defaults( pluginName, options ) #
 
 ## Purpose ##
 
 Set defaults for any property of a plugin.
 
-This allows numerous plugins of a single type to all use the same default values.  This can be done by either calling the instance method or by doing so in the popcorn constructor.
+This allows numerous plugins of a single type to use the same default values. This can be done by either calling the instance method or by defining properties in the Popcorn constructor's options object parameter.
 
 ## Options ##
 
-* **pluginName** - a string of the name of the plugin in which you want to set default values for
-* **options** - is an object that contains the values that will be defaulted for the given plugin
+* `**pluginName**` - string. The name of the plugin in which you want to set default values for
+* `**options**` - object. Property list and values that will be defaulted for the named plugin.
 
 ## Use Cases ##
 

instance-methods/_posts/2012-12-12-disable.md

@@ -1,12 +1,12 @@
-# disable #
+# disable( pluginName ) #
 
 ## Purpose ##
 
 Disable a plugin; stops the playback events for a specified plugin of a calling Popcorn instance.
 
 ## Options ##
 
-* **pluginName** - a string of the name of the plugin that will disabled
+* `**pluginName**` - string. The name of the plugin that will disabled.
 
 ## Example ##
 

instance-methods/_posts/2012-12-12-duration.md

@@ -1,8 +1,8 @@
-# duration #
+# duration() #
 
 ## Purpose ##
 
-Get the videos duration.  If the duration is not yet available, NaN will be returned.
+Get the media's duration in seconds. If the duration is not yet available, NaN will be returned.
 
 ## Options ##
 

instance-methods/_posts/2012-12-12-enable.md

@@ -1,13 +1,13 @@
-# enable #
+# enable( pluginName ) #
 
 ## Purpose ##
 
 Enable a previously disabled plugin of a calling Popcorn instance.
 
 ## Options ##
 
-* **pluginName** - a string of the name of the plugin that will disabled
+* `**pluginName**` - a string of the name of the plugin that will disabled
 
 ## Example ##
 
-* enable a previously disabled plugin [jsFiddle](http://jsfiddle.net/popcornjs/4Ps9x/) 
+* enable a previously disabled plugin [jsFiddle](http://jsfiddle.net/popcornjs/4Ps9x/)

instance-methods/_posts/2012-12-12-exec.md

@@ -1,13 +1,13 @@
-# exec #
+# exec( time, callback ) #
 
 ## Purpose ##
 
-Execute an arbitrary callback function at a specific time in seconds
+Execute an arbitrary function at a specific time
 
 ## Options ##
 
-* **time** - time location in seconds to execute callback function
-* **callback** - function to execute at the given **time**
+* `**time**` - number of seconds or SMPTE format string. The time in which the cue will be fired at
+* `**callback**` - callback. Function to execute at the given `**time**`
 
 ## Use Cases ##
 
@@ -16,4 +16,4 @@ Execute an arbitrary callback function at a specific time in seconds
 
 ## Example ##
 
-* console.log some data at 1 second [jsFiddle](http://jsfiddle.net/popcornjs/6SzsX/) 
+* console.log some data at 1 second [jsFiddle](http://jsfiddle.net/popcornjs/6SzsX/)

instance-methods/_posts/2012-12-12-listen.md

@@ -1,21 +1,20 @@
-# listen #
+# listen( eventName, callback ) #
 
 ## Purpose ##
 
 Bind an event handling callback to an event. Allows custom events.
 
 Any of the follow event types may be used with .listen() : loadstart, progress, suspend, emptied, stalled, play, pause, loadedmetadata, loadeddata, waiting, playing, canplay, canplaythrough, seeking, seeked, timeupdate, ended, ratechange, durationchange, volumechange.
 
-Listen also excepts custom events.
 
 ## Options ##
 
-* **eventName** - the name of the event to listen for
-* **callback** - the function that will get fired when the event is triggered
+* `**eventName**` - string. Name of the event to listen for
+* `**callback**` - callback. The function to execute when an event matching `eventName` is triggered.
 
 ## Use Cases ##
 
-* You want to perform some action when an event happens, i.e, show a googlemap when the video is paused
+* Perform an action when an event occurs, i.e, show a googlemap when the video is paused
 
 ## Examples ##
 

instance-methods/_posts/2012-12-12-mute.md

@@ -1,8 +1,10 @@
-# mute #
+# mute() #
 
 ## Purpose ##
 
-Toggle muting of the video, switching whether the video is muted or not.
+Toggle the media volume off, whether the media is currently muted or not.
+
+Calling the `.mute()` method will trigger a `**volumechange**` event.
 
 A mute event will be fired when mute is triggered
 

instance-methods/_posts/2012-12-12-pause.md

@@ -0,0 +1,16 @@
+# pause( [time] ) #
+
+## Purpose ##
+
+Pause the video.
+
+ - Calling the `.pause()` method will trigger a `**pause**` event.
+
+## Options ##
+
+* `**time**` - number of seconds or SMPTE format string. Optional parameter that will seek to a specified time and pause the media, short hand for `.currentTime( time ).pause()`;
+
+## Example ##
+
+* play the video [jsFiddle](http://jsfiddle.net/popcornjs/a4t4U/)
+* play the video and at 1 second seek to 3 seconds and continue playing using shorthand [jsFiddle](http://jsfiddle.net/popcornjs/hhtEA/)

instance-methods/_posts/2012-12-12-play.md

@@ -1,14 +1,16 @@
-# play #
+# play( [time] ) #
 
 ## Purpose ##
 
 Play the video.
 
-When the video plays a play event is triggered
+ - Calling the `.play()` method will trigger a `**play**` event.
+ - Calling the `.play()` method will trigger a `**playing**` event.
+ - Calling the `.play()` method will trigger `**timeupdate**` events.
 
 ## Options ##
 
-* **val** -  optional parameter that will seek to a specified time ( in seconds ) and play the video, short hand for .currentTime( val ).play();
+* `**time**` - number of seconds or SMPTE format string. Optional parameter that will seek to a specified time and play the media, short hand for `.currentTime( time ).play()`;
 
 ## Example ##
 

instance-methods/_posts/2012-12-12-playbackrate.md

@@ -1,12 +1,12 @@
-# playbackrate #
+# playbackrate( [rate] ) #
 
 ## Purpose ##
 
-Get/set the Popcorn video object instance playbackRate
+Get or set playbackrate of calling Popcorn instance
 
 ## Options ##
 
-* **rate** - an optional parameter that if it exists will set the playback rate, and if it does not, will return the playback rate
+* `**rate**` - number. Optional parameter that will set the playbackrate if provided and return the playbackrate if not.
 
 ## Example ##
 

instance-methods/_posts/2012-12-12-position.md

@@ -1,8 +1,8 @@
-# position #
+# position() #
 
 ## Purpose ##
 
-Get the calculated top, right, bottom, left, width & height of a calling Popcorn instance.
+Get an object containing the calculated `top`, `right`, `bottom`, `left`, `width` & `height` of a calling Popcorn instance.
 
 ## Options ##
 

instance-methods/_posts/2012-12-12-roundTime.md

@@ -2,7 +2,7 @@
 
 ## Purpose ##
 
-roundTime() returns the media's current time rounded to the closest second. roundTime() takes no arguments.
+`roundTime()` returns the media's current time rounded to the closest second.
 
 ## Options ##
 
@@ -18,4 +18,4 @@ roundTime() returns the media's current time rounded to the closest second. roun
 
 ## Related ##
 
-* currentTime()
+* `currentTime()`

instance-methods/_posts/2012-12-12-toggle.md

@@ -2,11 +2,11 @@
 
 ## Purpose ##
 
-toggle is used to turn on and off events of plugin type.  This provides the user with the ability to easily turn on and off events as they see fit. Something to note is that toggling events on/off does not mean that they will be hidden when toggled off.  It simply means that events will not longer be fired of that plugin type, i.e start, end, onFrame will not be fired if toggled off. toggle takes the following argument:
+`toggle()` allows you to easily turn plugin events of a specified type on and off. Note that toggling events on/off does not mean that they will be hidden when toggled off. It simply means that events of that type will no longer be fired, i.e `start`, `end`, `frame` will not be fired if toggled off.
 
 ## Options ##
 
-* **pluginName** - a string of the name of the plugin, i.e. footnote
+* `**pluginName**` - string. The name of the plugin, i.e. "footnote"
 
 ## Use Cases ##
 

instance-methods/_posts/2012-12-12-trigger.md

@@ -1,4 +1,4 @@
-# Trigger #
+# trigger( eventName, dataObject ) #
 
 ## Purpose ##
 
@@ -10,14 +10,21 @@ Trigger also accepts custom events.
 
 ## Options ##
 
-* **eventName** - the name of the event to be triggered
-* **dataObject** - optional data object
+* `**eventName**` - string. Name of the event to be triggered
+* `**dataObject**` - object. Optional data object
 
 ## Use Cases ##
 
-* Trigger an event to be fired when something happens, i.e., the video reaches halfway done, so trigger custom event "halfdone" which is listened for somewhere else
+* Forcefully trigger an event when something happens, i.e., the video reaches halfway done, so trigger custom event "halfdone" which can be listened for
 
 ## Examples ##
 
 * Trigger play [jsFiddle](http://jsfiddle.net/popcornjs/r8wVe/)
 * When half of the video has loaded, pass along a data object and log some data [jsFiddle](http://jsfiddle.net/popcornjs/GKkQx/)
+
+
+## Related ##
+
+* `listen( eventName, callback )`
+* `unlisten( eventName, callback )`
+

instance-methods/_posts/2012-12-12-unlisten.md

@@ -1,13 +1,13 @@
-# unlisten #
+# unlisten( eventName, callback ) #
 
 ## Purpose ##
 
-Unbind all events of specified type, or by string name
+Remove all or one listener of a specific event
 
 ## Options ##
 
-* **eventName** - either a native or custome event name
-* **callbackName** - string; named callback
+* `**eventName**` - string. either a native or custome event name
+* `**callbackName**` - string. named callback
 
 ## Example ##
 

instance-methods/_posts/2012-12-12-unmute.md

@@ -2,15 +2,17 @@
 
 ## Purpose ##
 
-unmute() simply unmutes the media of a given instance.  If the media is already not muted, nothing will happen. unmute() takes no arguments.
+Toggle the media volume on, whether the media is currently muted or not.
+
+ - Calling the `.unmute()` method will trigger a `**volumechange**` event.
 
 ## Use Cases ##
 
-* A video is muted and you want to programmatically unmute the media
+* If currently muted, programmatically unmute the media.
 
 ## Example ##
 
-* Unmutes a video that begins muted [jsFiddle](http://jsfiddle.net/popcornjs/kMXzC/)
+* Unmutes media that begins muted [jsFiddle](http://jsfiddle.net/popcornjs/kMXzC/)
 
 ## Related ##