docs: jsdoc for ads components (#340)

jsdoc for ads components

package.json

@@ -14,7 +14,9 @@
     "eslint": "eslint . --color",
     "flow": "flow check",
     "commit:dist": "git add --force --all dist && (git commit -m 'chore: update dist' || exit 0)",
-    "precommit": "lint-staged"
+    "precommit": "lint-staged",
+    "docs:generate": "documentation build flow-typed/** src/** -f md -o docs/api.md",
+    "docs:serve": "documentation serve flow-typed/** src/** --watch"
   },
   "lint-staged": {
     "*.{js,jsx}": [
@@ -47,6 +49,7 @@
     "chai": "^3.5.0",
     "cross-env": "^3.1.4",
     "css-loader": "^0.28.4",
+    "documentation": "^8.1.2",
     "eslint": "^3.10.0",
     "eslint-config-prettier": "^2.9.0",
     "eslint-loader": "^1.6.1",

src/ads/ad-break.js

@@ -1,4 +1,9 @@
 // @flow
+
+/**
+ * @class AdBreak
+ * @param {PKAdBreakOptions} options - Ad break data options.
+ */
 class AdBreak {
   _type: ?string;
   _position: ?number;
@@ -10,14 +15,29 @@ class AdBreak {
     this._numAds = options.numAds;
   }
 
+  /**
+   * @instance
+   * @memberof AdBreak
+   * @return {string} - Ad break type - pre/mid/post.
+   */
   get type(): ?string {
     return this._type;
   }
 
+  /**
+   * @instance
+   * @memberof AdBreak
+   * @return {string} - Ad break position on the playback timeline.
+   */
   get position(): ?number {
     return this._position;
   }
 
+  /**
+   * @instance
+   * @memberof AdBreak
+   * @return {string} - The number of ads inside the ad break.
+   */
   get numAds(): ?number {
     return this._numAds;
   }

src/ads/ad.js

@@ -1,5 +1,10 @@
 // @flow
 
+/**
+ * @class Ad
+ * @param {string} id - Ad ID.
+ * @param {PKAdOptions} options - Ad data options.
+ */
 class Ad {
   _id: string;
   _url: ?string;
@@ -31,58 +36,128 @@ class Ad {
     this._bitrate = options.bitrate || 0;
   }
 
+  /**
+   * @instance
+   * @memberof Ad
+   * @return {string} - Ad ID.
+   */
   get id(): string {
     return this._id;
   }
 
+  /**
+   * @instance
+   * @memberof Ad
+   * @return {string} - Ad ID.
+   */
   get contentType(): ?string {
     return this._contentType;
   }
 
+  /**
+   * @instance
+   * @memberof Ad
+   * @return {string} - Ad URL.
+   */
   get url(): ?string {
     return this._url;
   }
 
+  /**
+   * @instance
+   * @memberof Ad
+   * @return {string} - Ad title.
+   */
   get title(): ?string {
     return this._title;
   }
 
+  /**
+   * @instance
+   * @memberof Ad
+   * @return {string} - Ad position inside the ad break.
+   */
   get position(): ?number {
     return this._position;
   }
 
+  /**
+   * @instance
+   * @memberof Ad
+   * @return {string} - Ad duration.
+   */
   get duration(): ?number {
     return this._duration;
   }
 
+  /**
+   * @instance
+   * @memberof Ad
+   * @return {string} - Ad click through URL.
+   */
   get clickThroughUrl(): ?string {
     return this._clickThroughUrl;
   }
 
+  /**
+   * @instance
+   * @memberof Ad
+   * @return {string} - Ad poster URL.
+   */
   get posterUrl(): ?string {
     return this._posterUrl;
   }
 
+  /**
+   * @instance
+   * @memberof Ad
+   * @return {string} - Ad skip offset.
+   */
   get skipOffset(): ?number {
     return this._skipOffset;
   }
 
+  /**
+   * @instance
+   * @memberof Ad
+   * @return {string} - Whether the ad is linear.
+   */
   get linear(): ?boolean {
     return this._linear;
   }
 
+  /**
+   * @instance
+   * @memberof Ad
+   * @return {string} - Ad width.
+   */
   get width(): number {
     return this._width;
   }
 
+  /**
+   * @instance
+   * @memberof Ad
+   * @return {string} - Ad height.
+   */
   get height(): number {
     return this._height;
   }
 
+  /**
+   * @instance
+   * @memberof Ad
+   * @return {string} - Ad bitrate.
+   */
   get bitrate(): number {
     return this._bitrate;
   }
 
+  /**
+   * @instance
+   * @memberof Ad
+   * @return {string} - Whether the ad is skippable or not.
+   */
   get skippable(): boolean {
     return !!(this.skipOffset && this.skipOffset > 0);
   }

src/ads/ads-controller.js

@@ -9,6 +9,11 @@ import Error from '../error/error';
 import {AdBreak} from './ad-break';
 import {Ad} from './ad';
 
+/**
+ * @class AdsController
+ * @param {Player} player - The player.
+ * @param {IAdsController} adsPluginController - The controller of the current ads plugin instance.
+ */
 class AdsController extends FakeEventTarget implements IAdsController {
   _player: Player;
   _adsPluginController: IAdsController;
@@ -18,11 +23,6 @@ class AdsController extends FakeEventTarget implements IAdsController {
   _adBreak: ?AdBreak;
   _ad: ?Ad;
 
-  /**
-   * The ads controller.
-   * @param {Player} player - The player.
-   * @param {IAdsController} adsPluginController - the controller of the current plugin instance.
-   */
   constructor(player: Player, adsPluginController: IAdsController) {
     super();
     this._player = player;
@@ -32,48 +32,54 @@ class AdsController extends FakeEventTarget implements IAdsController {
   }
 
   /**
-   * Getter to the no more ads to play indication.
+   * @instance
+   * @memberof AdsController
    * @returns {boolean} - Whether all ads completed.
    */
   get allAdsCompleted(): boolean {
     return this._allAdsCompleted;
   }
 
   /**
-   * @public
+   * @instance
+   * @memberof AdsController
    * @returns {boolean} - Whether we're in an ad break.
    */
   isAdBreak(): boolean {
     return !!this._adBreak;
   }
 
   /**
-   * @public
-   * @returns {boolean} - The ad breaks layout (cue points).
+   * @instance
+   * @memberof AdsController
+   * @returns {Array<number>} - The ad breaks layout (cue points).
    */
   getAdBreaksLayout(): Array<number> {
     return this._adBreaksLayout;
   }
 
   /**
-   * @public
-   * @returns {?AdBreak} - Gets the current ad break info.
+   * @instance
+   * @memberof AdsController
+   * @returns {?AdBreak} - Gets the current ad break data.
    */
   getAdBreak(): ?AdBreak {
     return this._adBreak;
   }
 
   /**
-   * @public
-   * @returns {?AdBreak} - Gets the current ad info.
+   * @instance
+   * @memberof AdsController
+   * @returns {?Ad} - Gets the current ad data.
    */
   getAd(): ?Ad {
     return this._ad;
   }
 
   /**
    * Skip on an ad.
-   * @public
+   * @instance
+   * @memberof AdsController
    * @returns {void}
    */
   skipAd(): void {
@@ -83,7 +89,8 @@ class AdsController extends FakeEventTarget implements IAdsController {
   /**
    * Play an ad on demand.
    * @param {string} adTagUrl - The ad tag url to play.
-   * @public
+   * @instance
+   * @memberof AdsController
    * @returns {void}
    */
   playAdNow(adTagUrl: string): void {