Merge pull request #644 from tf/js-docs-3

Use doclets.io for JavaScript API reference

.doclets.yml

@@ -0,0 +1,3 @@
+dir: app/assets/javascripts/
+branches:
+  - master

README.md

@@ -12,7 +12,8 @@ For a high level introduction and example Pageflow stories see
 
 * [Getting Started](https://github.com/codevise/pageflow/wiki/Getting-Started)
 * [Guides](https://github.com/codevise/pageflow/blob/master/doc/index.md)
-* [Theme Settings](http://codevise.github.io/pageflow/theme/master/)
+* [JavaScript API Reference](https://doclets.io/codevise/pageflow/master)
+* [Theme API Reference](http://codevise.github.io/pageflow/theme/master/)
 
 ## Updating
 

app/assets/javascripts/pageflow/audio.js

@@ -2,6 +2,11 @@
 //= require ./audio/player_pool
 //= require ./audio/multi_player
 
+/**
+ * Playing audio files.
+ * @alias pageflow.audio
+ * @member
+ */
 pageflow.Audio = function(options) {
   this.getSources = options.getSources || function(audioFileId) {
     return options.audioFiles[audioFileId] || '';
@@ -10,12 +15,15 @@ pageflow.Audio = function(options) {
   /**
    * Creates a player for the given audio file.
    *
-   * @param [String|Numberic] audioFileId  Id of the audio file to play possibly with a suffix.
-   * @param [Object] options  Options to pass on player creation
+   * @param {string|number} audioFileId
+   *   Id of the audio file to play. The id can be of the form
+   *   `"5.suffix"` to distinguish multiple occurences of the same
+   *   audio file for example inside a pageflow.Audio.PlayerPool;
    *
-   * The audio file id can be of the form `"5.suffix"` to distinguish
-   * multiple occurences of the same audio file for example inside a
-   * pageflow.Audio.PlayerPool;
+   * @param {Object} [options]
+   *   Options to pass on player creation
+   *
+   * @static
    */
   this.createPlayer = function(audioFileId, options) {
     var sources = this.getSources(removeSuffix(audioFileId));
@@ -31,15 +39,22 @@ pageflow.Audio = function(options) {
   };
 
   /**
-   * @option options [Numeric] fadeDuration  Time in milliseconds to fade
-   *   audios in and out.
-   * @option options [Boolean] playFromBeginning  Always restart audio
-   *   files from the beginning. Defaults to false.
-   * @option options [Boolean] rewindOnChange  Play from beginning when
-   *   changing audio files. Defaults to false.
-   *
-   * Furthermore all options supported by pageflow.AudioPlayer can be
-   * passed.
+   * Create a `MultiPlayer` to play and fade between multiple audio
+   * files.
+   *
+   * @param {Object} [options]
+   *   All options supported by pageflow.AudioPlayer can be passed.
+   *
+   * @param {number} [options.fadeDuration]
+   *   Time in milliseconds to fade audios in and out.
+   *
+   * @param {boolean} [options.playFromBeginning=false]
+   *   Always restart audio files from the beginning.
+   *
+   * @param {boolean} [options.rewindOnChange=false]
+   *   Play from beginning when changing audio files.
+   *
+   * @return {pageflow.Audio.MultiPlayer}
    */
   this.createMultiPlayer = function(options) {
     return new pageflow.Audio.MultiPlayer(
@@ -59,4 +74,4 @@ pageflow.Audio = function(options) {
 
 pageflow.Audio.setup = function(options) {
   pageflow.audio = new pageflow.Audio(options);
-};
+};

app/assets/javascripts/pageflow/audio/multi_player.js

@@ -1,3 +1,8 @@
+/**
+ * Play and fade between multiple audio files.
+ *
+ * @class
+ */
 pageflow.Audio.MultiPlayer = function(pool, options) {
   if (options.crossFade && options.playFromBeginning) {
     throw 'pageflow.Audio.MultiPlayer: The options crossFade and playFromBeginning can not be used together at the moment.';
@@ -7,10 +12,16 @@ pageflow.Audio.MultiPlayer = function(pool, options) {
   var currentId = null;
   var that = this;
 
+  /**
+   * Continue playback.
+   */
   this.resume = function() {
     return current.play();
   };
 
+  /**
+   * Continue playback with fade in.
+   */
   this.resumeAndFadeIn = function() {
     return current.playAndFadeIn(options.fadeDuration);
   };
@@ -124,4 +135,4 @@ pageflow.Audio.MultiPlayer = function(pool, options) {
   }
 };
 
-_.extend(pageflow.Audio.MultiPlayer.prototype, Backbone.Events);
+_.extend(pageflow.Audio.MultiPlayer.prototype, Backbone.Events);

app/assets/javascripts/pageflow/audio_player.js

@@ -8,6 +8,20 @@
 //= require ./audio_player/rewind_method
 //= require ./audio_player/pause_in_background
 
+/**
+ * Playing audio sources
+ *
+ * @param {Object[]} sources
+ * List of sources for audio element.
+ *
+ * @param {string} sources[].type
+ * Mime type of the audio.
+ *
+ * @param {string} sources[].src
+ * Url of the audio.
+ *
+ * @class
+ */
 pageflow.AudioPlayer = function(sources, options) {
   options = options || {};
 
@@ -109,4 +123,4 @@ pageflow.AudioPlayer.fromAudioTag = function(element, options) {
 pageflow.AudioPlayer.fromScriptTag = function(element, options) {
   var sources = element.length ? JSON.parse(element.text()) : [];
   return new pageflow.AudioPlayer(sources, options);
-};
+};

app/assets/javascripts/pageflow/audio_player/rewind_method.js

@@ -2,6 +2,8 @@ pageflow.AudioPlayer.rewindMethod = function(player) {
   /**
    * Seek to beginning of file. If already at the beginning do
    * nothing.
+   *
+   * @alias pageflow.AudioPlayer#rewind
    */
   player.rewind = function() {
     if (player.position > 0) {
@@ -14,4 +16,4 @@ pageflow.AudioPlayer.rewindMethod = function(player) {
       return new $.Deferred().resolve().promise();
     }
   };
-};
+};

app/assets/javascripts/pageflow/browser.js

@@ -22,6 +22,7 @@ pageflow.browser = (function(){
      * @param name [String] Name of the feature. Can contain whitespace.
      * @param test [Function] A function that either returns `true` or
      *   `false` or a promise that resolves to `true` or `false`.
+     * @memberof pageflow.browser
      */
     feature: function(name, test) {
       var s = name.replace(/ /g, '_');
@@ -50,6 +51,7 @@ pageflow.browser = (function(){
      *
      * @param name [String] Name of the feature.
      * @return [Boolean]
+     * @memberof pageflow.browser
      */
     has: function(name) {
       if (this.ready().state() != 'resolved') {
@@ -67,6 +69,7 @@ pageflow.browser = (function(){
      * A promise that is resolved once feature detection has finished.
      *
      * @return [Promise]
+     * @memberof pageflow.browser
      */
     ready: function() {
       return ready.promise();

app/assets/javascripts/pageflow/cookies.js

@@ -1,7 +1,4 @@
-/**
- *  https://developer.mozilla.org/en-US/docs/Web/API/document.cookie
- */
-
+//  https://developer.mozilla.org/en-US/docs/Web/API/document.cookie
 pageflow.cookies = {
   getItem: function (sKey) {
     if (!sKey) { return null; }