Edit pass for jsdco comments (#34)

Author: mgblythe

src/embed.ts

@@ -73,35 +73,35 @@ export abstract class Embed {
   allowedEvents = [];
 
   /**
-   * Gets or set the event handler registered for this embed component
+   * Gets or sets the event handler registered for this embed component.
    * 
    * @type {IInternalEventHandler<any>[]}
    */
   eventHandlers: IInternalEventHandler<any>[];
 
   /**
-   * Gets or sets the Power BI embed service
+   * Gets or sets the Power BI embed service.
    * 
    * @type {service.Service}
    */
   service: service.Service;
 
   /**
-   * Gets or sets the HTML element containing the Power BI embed component
+   * Gets or sets the HTML element that contains the Power BI embed component.
    * 
    * @type {HTMLElement}
    */
   element: HTMLElement;
 
   /**
-   * Gets or sets the HTML iframe element that renders the Power BI embed component
+   * Gets or sets the HTML iframe element that renders the Power BI embed component.
    * 
    * @type {HTMLIFrameElement}
    */
   iframe: HTMLIFrameElement;
 
   /**
-   * Gets or sets the configuration settings for the embed component
+   * Gets or sets the configuration settings for the Power BI embed component.
    * 
    * @type {IInternalEmbedConfiguration}
    */
@@ -110,8 +110,8 @@ export abstract class Embed {
   /**
    * Creates an instance of Embed.
    * 
-   * Note: there is circular reference between embeds and service
-   * The service has list of all embeds on the host page, and each embed has reference to the service that created it.
+   * Note: there is circular reference between embeds and the service, because
+   * the service has a list of all embeds on the host page, and each embed has a reference to the service that created it.
    * 
    * @param {service.Service} service
    * @param {HTMLElement} element
@@ -178,10 +178,9 @@ export abstract class Embed {
   }
 
   /**
-   * Removes event handler(s) from list of handlers.
-   * 
-   * If reference to existing handle function is specified remove specific handler.
-   * If handler is not specified, remove all handlers for the event name specified.
+   * Removes one or more event handlers from the list of handlers.
+   * If a reference to the existing handle function is specified, remove the specific handler.
+   * If the handler is not specified, remove all handlers for the event name specified.
    * 
    * ```javascript
    * report.off('pageChanged')
@@ -218,7 +217,7 @@ export abstract class Embed {
   }
 
   /**
-   * Adds event handler for specific event.
+   * Adds an event handler for a specific event.
    * 
    * ```javascript
    * report.on('pageChanged', (event) => {
@@ -244,7 +243,7 @@ export abstract class Embed {
   }
 
   /**
-   * Get access token from first available location: config, attribute, global.
+   * Gets an access token from the first available location: config, attribute, global.
    * 
    * @private
    * @param {string} globalAccessToken
@@ -261,7 +260,7 @@ export abstract class Embed {
   }
 
   /**
-   * Get embed url from first available location: options, attribute.
+   * Gets an embed url from the first available location: options, attribute.
    * 
    * @private
    * @returns {string}
@@ -277,8 +276,8 @@ export abstract class Embed {
   }
 
   /**
-   * Get unique id from first available location: options, attribute.
-   * If neither is provided generate unique string.
+   * Gets a unique ID from the first available location: options, attribute.
+   * If neither is provided generate a unique string.
    * 
    * @private
    * @returns {string}
@@ -288,23 +287,23 @@ export abstract class Embed {
   }
 
   /**
-   * Get report id from first available location: options, attribute.
+   * Gets the report ID from the first available location: options, attribute.
    * 
    * @abstract
    * @returns {string}
    */
   abstract getId(): string;
 
   /**
-   * Request the browser to make the component's iframe fullscreen.
+   * Requests the browser to render the component's iframe in fullscreen mode.
    */
   fullscreen(): void {
     const requestFullScreen = this.iframe.requestFullscreen || this.iframe.msRequestFullscreen || this.iframe.mozRequestFullScreen || this.iframe.webkitRequestFullscreen;
     requestFullScreen.call(this.iframe);
   }
 
   /**
-   * Exit fullscreen.
+   * Requests the browser to exit fullscreen mode.
    */
   exitFullscreen(): void {
     if (!this.isFullscreen(this.iframe)) {
@@ -317,8 +316,8 @@ export abstract class Embed {
 
 
   /**
-   * Return true if iframe is fullscreen,
-   * otherwise return false
+   * Returns true if the iframe is rendered in fullscreen mode,
+   * otherwise returns false.
    * 
    * @private
    * @param {HTMLIFrameElement} iframe

src/ifilterable.ts

@@ -9,20 +9,20 @@ import * as models from 'powerbi-models';
  */
 export interface IFilterable {
   /**
-   * Gets the filters currently applied to the object
+   * Gets the filters currently applied to the object.
    * 
    * @returns {(Promise<(models.IBasicFilter | models.IAdvancedFilter)[]>)}
    */
   getFilters(): Promise<(models.IBasicFilter | models.IAdvancedFilter)[]>;
   /**
-   * Replaces all filters on the current object with the specified filter values
+   * Replaces all filters on the current object with the specified filter values.
    * 
    * @param {((models.IBasicFilter | models.IAdvancedFilter)[])} filters
    * @returns {Promise<void>}
    */
   setFilters(filters: (models.IBasicFilter | models.IAdvancedFilter)[]): Promise<void>;
   /**
-   * Removes all filters from the current object
+   * Removes all filters from the current object.
    * 
    * @returns {Promise<void>}
    */

src/page.ts

@@ -37,8 +37,7 @@ export class Page implements IPageNode, IFilterable {
   name: string;
 
   /**
-   * The user defined display name of the report page
-   * This can be undefined in cases where page is created manually
+   * The user defined display name of the report page, which is undefined if the page is created manually
    * 
    * @type {string}
    */
@@ -58,7 +57,7 @@ export class Page implements IPageNode, IFilterable {
   }
 
   /**
-   * Gets all page level filters within report
+   * Gets all page level filters within the report.
    * 
    * ```javascript
    * page.getFilters()
@@ -98,7 +97,7 @@ export class Page implements IPageNode, IFilterable {
   }
 
   /**
-   * Remove all filters on this page within the report
+   * Removes all filters from this page of the report.
    * 
    * ```javascript
    * page.removeFilters();
@@ -111,7 +110,7 @@ export class Page implements IPageNode, IFilterable {
   }
 
   /**
-   * Make the current page the active page of the report.
+   * Makes the current page the active page of the report.
    * 
    * ```javascripot
    * page.setActive();
@@ -150,13 +149,13 @@ export class Page implements IPageNode, IFilterable {
   }
 
   /**
-   * Creates new Visual object given a name of the visual.
+   * Creates a Visual object given a name for the visual.
    * 
    * Normally you would get Visual objects by calling `page.getVisuals()` but in the case
-   * that the visual name is known and you want to perform an action on a visaul such as setting a filters
+   * that the visual name is known and you want to perform an action on a visual such as setting a filter
    * without having to retrieve it first you can create it directly.
    * 
-   * Note: Since you are creating the visual manually there is no guarantee that the visual actually exists in the report and the subsequence requests could fail.
+   * Note: Because you are creating the visual manually there is no guarantee that the visual actually exists in the report and the subsequence requests could fail.
    * 
    * ```javascript
    * const visual = report.page('ReportSection1').visual('BarChart1');

src/powerbi.ts

@@ -34,9 +34,9 @@ declare global {
 }
 
 /**
- * Make PowerBi available on global object for use in apps without module loading support.
- * Save class to allow creating an instance of the service.
- * Create instance of class with default config for normal usage.
+ * Makes Power BI available to the global object for use in applications that don't have module loading support.
+ *
+ * Note: create an instance of the class with the default configuration for normal usage, or save the class so that you can create an instance of the service.
  */
 var powerbi = new service.Service(factories.hpmFactory, factories.wpmpFactory, factories.routerFactory);
 window.powerbi = powerbi;

src/report.ts

@@ -20,7 +20,7 @@ export interface IReportNode {
 }
 
 /**
- * A Power BI Report embed component
+ * The Power BI Report embed component
  * 
  * @export
  * @class Report
@@ -57,10 +57,10 @@ export class Report extends embed.Embed implements IReportNode, IFilterable {
   }
 
   /**
-   * This adds backwards compatibility for older config which used the reportId query param to specify report id.
-   * E.g. http://embedded.powerbi.com/appTokenReportEmbed?reportId=854846ed-2106-4dc2-bc58-eb77533bf2f1
+   * Adds backwards compatibility for the previous load configuration, which used the reportId query parameter to specify the report ID
+   * (e.g. http://embedded.powerbi.com/appTokenReportEmbed?reportId=854846ed-2106-4dc2-bc58-eb77533bf2f1).
    * 
-   * By extracting the id we can ensure id is always explicitly provided as part of the load configuration.
+   * By extracting the ID we can ensure that the ID is always explicitly provided as part of the load configuration.
    * 
    * @static
    * @param {string} url
@@ -79,7 +79,7 @@ export class Report extends embed.Embed implements IReportNode, IFilterable {
   }
 
   /**
-   * Get filters that are applied at the report level
+   * Gets filters that are applied at the report level.
    * 
    * ```javascript
    * // Get filters applied at report level
@@ -100,7 +100,7 @@ export class Report extends embed.Embed implements IReportNode, IFilterable {
   }
 
   /**
-   * Get report id from first available location: options, attribute, embed url.
+   * Gets the report ID from the first available location: options, attribute, embed url.
    * 
    * @returns {string}
    */
@@ -115,7 +115,7 @@ export class Report extends embed.Embed implements IReportNode, IFilterable {
   }
 
   /**
-   * Get the list of pages within the report
+   * Gets the list of pages within the report.
    * 
    * ```javascript
    * report.getPages()
@@ -139,13 +139,13 @@ export class Report extends embed.Embed implements IReportNode, IFilterable {
   }
 
   /**
-   * Create new Page instance.
+   * Creates an instance of a Page.
    * 
-   * Normally you would get Page objects by calling `report.getPages()` but in the case
+   * Normally you would get Page objects by calling `report.getPages()`, but in the case
    * that the page name is known and you want to perform an action on a page without having to retrieve it
    * you can create it directly.
    * 
-   * Note: Since you are creating the page manually there is no guarantee that the page actually exists in the report and the subsequence requests could fail.
+   * Note: Because you are creating the page manually there is no guarantee that the page actually exists in the report, and subsequent requests could fail.
    * 
    * ```javascript
    * const page = report.page('ReportSection1');
@@ -161,8 +161,7 @@ export class Report extends embed.Embed implements IReportNode, IFilterable {
   }
 
   /**
-   * Print the active page of the report.
-   * (Invokes window.print() on embed iframe)
+   * Prints the active page of the report by invoking `window.print()` on the embed iframe component.
    */
   print(): Promise<void> {
     return this.service.hpm.post<models.IError[]>('/report/print', null, { uid: this.config.uniqueId }, this.iframe.contentWindow)
@@ -175,7 +174,7 @@ export class Report extends embed.Embed implements IReportNode, IFilterable {
   }
 
   /**
-   * Refreshes data sources for report.
+   * Refreshes data sources for the report.
    * 
    * ```javascript
    * report.refresh();
@@ -192,7 +191,7 @@ export class Report extends embed.Embed implements IReportNode, IFilterable {
   }
 
   /**
-   * Remove all filters at report level
+   * Removes all filters at the report level.
    * 
    * ```javascript
    * report.removeFilters();
@@ -205,7 +204,7 @@ export class Report extends embed.Embed implements IReportNode, IFilterable {
   }
 
   /**
-   * Set the active page
+   * Sets the active page of the report.
    * 
    * ```javascript
    * report.setPage("page2")
@@ -228,7 +227,7 @@ export class Report extends embed.Embed implements IReportNode, IFilterable {
   }
 
   /**
-   * Sets filters
+   * Sets filters at the report level.
    * 
    * ```javascript
    * const filters: [
@@ -252,7 +251,7 @@ export class Report extends embed.Embed implements IReportNode, IFilterable {
   }
 
   /**
-   * Update settings of report (filter pane visibility, page navigation visibility)
+   * Updates visibility settings for the filter pane and the page navigation pane.
    * 
    * ```javascript
    * const newSettings = {