From c0f9eeab44c7df9eb9e87392530ecbb387868657 Mon Sep 17 00:00:00 2001 From: Michael Blythe Date: Mon, 29 Aug 2016 12:52:15 -0700 Subject: [PATCH] Edit pass for jsdco comments --- src/embed.ts | 41 +++++++++++++++++----------------- src/ifilterable.ts | 6 ++--- src/page.ts | 15 ++++++------- src/powerbi.ts | 6 ++--- src/report.ts | 33 ++++++++++++++-------------- src/service.ts | 55 +++++++++++++++++++++++----------------------- src/tile.ts | 2 +- src/util.ts | 10 ++++----- src/visual.ts | 8 +++---- 9 files changed, 86 insertions(+), 90 deletions(-) diff --git a/src/embed.ts b/src/embed.ts index f44381c9..7e63d67b 100644 --- a/src/embed.ts +++ b/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[]} */ eventHandlers: IInternalEventHandler[]; /** - * 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,7 +287,7 @@ 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} @@ -296,7 +295,7 @@ export abstract class Embed { 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; @@ -304,7 +303,7 @@ export abstract class Embed { } /** - * 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 diff --git a/src/ifilterable.ts b/src/ifilterable.ts index a9b09f52..0a9b7875 100644 --- a/src/ifilterable.ts +++ b/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} */ setFilters(filters: (models.IBasicFilter | models.IAdvancedFilter)[]): Promise; /** - * Removes all filters from the current object + * Removes all filters from the current object. * * @returns {Promise} */ diff --git a/src/page.ts b/src/page.ts index c1bd44e3..29a4e97c 100644 --- a/src/page.ts +++ b/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'); diff --git a/src/powerbi.ts b/src/powerbi.ts index 5a7ae057..b8878fd9 100644 --- a/src/powerbi.ts +++ b/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; \ No newline at end of file diff --git a/src/report.ts b/src/report.ts index 9b282b3c..b7d7e409 100644 --- a/src/report.ts +++ b/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 { return this.service.hpm.post('/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 = { diff --git a/src/service.ts b/src/service.ts index 01b4090a..3f9895d8 100644 --- a/src/service.ts +++ b/src/service.ts @@ -56,7 +56,7 @@ export interface IService { } /** - * The Power BI embed service. This is the entry point to embed Power BI components intor your application. + * The Power BI Service embed component, which is the entry point to embed all other Power BI components into your application * * @export * @class Service @@ -65,7 +65,7 @@ export interface IService { export class Service implements IService { /** - * List of components this service can embed. + * A list of components that this service can embed */ private static components: (typeof Report | typeof Tile)[] = [ Tile, @@ -73,7 +73,7 @@ export class Service implements IService { ]; /** - * Default configuration for service. + * The default configuration for the service */ private static defaultConfig: IServiceConfiguration = { autoEmbedOnContentLoaded: false, @@ -81,16 +81,16 @@ export class Service implements IService { }; /** - * Gets or sets the access token as fallback/global token to use when local token for report/tile is not provided. + * Gets or sets the access token as the global fallback token to use when a local token is not provided for a report or tile. * * @type {string} */ accessToken: string; - /** Configuration object */ + /**The Configuration object for the service*/ private config: IServiceConfiguration; - /** List of components (Reports/Tiles) that have been embedded using this service instance. */ + /** A list of Report and Tile components that have been embedded using this service instance. */ private embeds: embed.Embed[]; /** TODO: Look for way to make hpm private without sacraficing ease of maitenance. This should be private but in embed needs to call methods. */ hpm: hpm.HttpPostMessage; @@ -99,7 +99,7 @@ export class Service implements IService { private router: router.Router; /** - * Creates an instance of Power BI embed service. + * Creates an instance of a Power BI Service. * * @param {IHpmFactory} hpmFactory The http post message factory used in the postMessage communication layer * @param {IWpmpFactory} wpmpFactory The window post message factory used in the postMessage communication layer @@ -112,7 +112,7 @@ export class Service implements IService { this.router = routerFactory(this.wpmp); /** - * Add handler for report events + * Adds handler for report events. */ this.router.post(`/reports/:uniqueId/events/:eventName`, (req, res) => { const event: IEvent = { @@ -156,9 +156,7 @@ export class Service implements IService { } /** - * Handler for DOMContentLoaded which searches DOM for elements having 'powerbi-embed-url' attribute - * and automatically attempts to embed a powerbi component based on information from the attributes. - * Only runs if `config.autoEmbedOnContentLoaded` is true when the service is created. + * TODO: Add a description here * * @param {HTMLElement} [container] * @param {embed.IEmbedConfiguration} [config=undefined] @@ -172,9 +170,9 @@ export class Service implements IService { } /** - * Given an html element embed component based on configuration. - * If component has already been created and attached to element re-use component instance and existing iframe, - * otherwise create a new component instance + * Given a configuration based on an HTML element, + * if the component has already been created and attached to the element, reuses the component instance and existing iframe, + * otherwise creates a new component instance. * * @param {HTMLElement} element * @param {embed.IEmbedConfiguration} [config={}] @@ -195,8 +193,7 @@ export class Service implements IService { } /** - * Given an html element embed component base configuration. - * Save component instance on element for later lookup. + * Given a configuration based on a Power BI element, saves the component instance that reference the element for later lookup. * * @private * @param {IPowerBiElement} element @@ -209,7 +206,7 @@ export class Service implements IService { throw new Error(`Attempted to embed using config ${JSON.stringify(config)} on element ${element.outerHTML}, but could not determine what type of component to embed. You must specify a type in the configuration or as an attribute such as '${embed.Embed.typeAttribute}="${Report.type.toLowerCase()}"'.`); } - // Save type on configuration so it can be referenced later at known location + // Saves the type as part of the configuration so that it can be referenced later at a known location. config.type = componentType; const Component = utils.find(component => componentType === component.type.toLowerCase(), Service.components); @@ -225,7 +222,7 @@ export class Service implements IService { } /** - * Given and element which arleady contains embed, load with new configuration + * Given an element that already contains an embed component, load with a new configuration. * * @private * @param {IPowerBiElement} element @@ -244,16 +241,18 @@ export class Service implements IService { } /** - * Adds event handler for DOMContentLoaded which finds all elements in DOM with attribute powerbi-embed-url - * then attempts to initiate the embed process based on data from other powerbi-* attributes. - * (This is usually only useful for applications rendered on by the server since all the data needed will be available by the time the handler is called.) + * Adds an event handler for DOMContentLoaded, which searches the DOM for elements that have the 'powerbi-embed-url' attribute, + * and automatically attempts to embed a powerbi component based on information from other powerbi-* attributes. + * + * Note: Only runs if `config.autoEmbedOnContentLoaded` is true when the service is created. + * This handler is typically useful only for applications that are rendered on the server so that all required data is available when the handler is called. */ enableAutoEmbed(): void { window.addEventListener('DOMContentLoaded', (event: Event) => this.init(document.body), false); } /** - * Returns instance of component associated with element. + * Returns an instance of the component associated with the element. * * @param {HTMLElement} element * @returns {(Report | Tile)} @@ -269,7 +268,7 @@ export class Service implements IService { } /** - * Find embed instance by name / unique id provided. + * Finds an embed instance by the name or unique ID that is provided. * * @param {string} uniqueId * @returns {(Report | Tile)} @@ -279,7 +278,7 @@ export class Service implements IService { } /** - * Given an html element which has component embedded within it, remove the component from list of embeds, remove association with component, and remove the iframe. + * Given an HTML element that has a component embedded within it, removes the component from the list of embedded components, removes the association between the element and the component, and removes the iframe. * * @param {HTMLElement} element * @returns {void} @@ -291,11 +290,11 @@ export class Service implements IService { return; } - /** Remove component from internal list */ + /** Removes the component from an internal list of components. */ utils.remove(x => x === powerBiElement.powerBiEmbed, this.embeds); - /** Delete property from html element */ + /** Deletes a property from the HTML element. */ delete powerBiElement.powerBiEmbed; - /** Remove iframe from element */ + /** Removes the iframe from the element. */ const iframe = element.querySelector('iframe'); if (iframe) { iframe.remove(); @@ -303,7 +302,7 @@ export class Service implements IService { } /** - * Given an event object, find embed with matching type and id and invoke its handleEvent method with event. + * Given an event object, finds the embed component with the matching type and ID, and invokes its handleEvent method with the event object. * * @private * @param {IEvent} event diff --git a/src/tile.ts b/src/tile.ts index 65fe84fe..be865b46 100644 --- a/src/tile.ts +++ b/src/tile.ts @@ -11,7 +11,7 @@ export class Tile extends Embed { static type = "Tile"; /** - * The the id of the tile + * The ID of the tile * * @returns {string} */ diff --git a/src/util.ts b/src/util.ts index 3721bdf9..0365bc92 100644 --- a/src/util.ts +++ b/src/util.ts @@ -1,6 +1,6 @@ /** - * Raises a custom event with event data on the specified HTML element + * Raises a custom event with event data on the specified HTML element. * * @export * @param {HTMLElement} element @@ -24,7 +24,7 @@ export function raiseCustomEvent(element: HTMLElement, eventName: string, eventD } /** - * Finds the index of the first matching value in an array that matches the specified predicate + * Finds the index of the first value in an array that matches the specified predicate. * * @export * @template T @@ -49,7 +49,7 @@ export function findIndex(predicate: (x: T) => boolean, xs: T[]): number { } /** - * Findes the first matching value in an array that matches the specified predicate + * Finds the first value in an array that matches the specified predicate. * * @export * @template T @@ -70,7 +70,7 @@ export function remove(predicate: (x: T) => boolean, xs: T[]): void { // See: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/assign // TODO: replace in favor of using polyfill /** - * Copies the values of all enumerable own properties from one or more source objects to a target object. It will return the target object. + * Copies the values of all enumerable properties from one or more source objects to a target object, and returns the target object. * * @export * @param {any} args @@ -99,7 +99,7 @@ export function assign(...args) { } /** - * Generates a random 7 character string + * Generates a random 7 character string. * * @export * @returns {string} diff --git a/src/visual.ts b/src/visual.ts index 5d63ff70..d9fa1ebe 100644 --- a/src/visual.ts +++ b/src/visual.ts @@ -29,7 +29,7 @@ export class Visual implements IVisualNode, IFilterable { */ name: string; /** - * The parent Power BI page containing this visual + * The parent Power BI page that contains this visual * * @type {IPageNode} */ @@ -41,7 +41,7 @@ export class Visual implements IVisualNode, IFilterable { } /** - * Gets all page level filters within report + * Gets all page level filters within a report. * * ```javascript * visual.getFilters() @@ -59,7 +59,7 @@ export class Visual implements IVisualNode, IFilterable { } /** - * Remove all filters on this page within the report + * Removes all filters on this page of the report. * * ```javascript * visual.removeFilters(); @@ -72,7 +72,7 @@ export class Visual implements IVisualNode, IFilterable { } /** - * Set all filters at the visual level of the page + * Sets all filters at the visual level of the page. * * ```javascript * visual.setFilters(filters)