docs: fixing comment newlines

Author: David Joy

src/config.js

@@ -1,5 +1,9 @@
 /**
- * The configuration module provides utilities for working with an application's configuration document (ConfigDocument).  This module uses `process.env` to import configuration variables from the command-line build process.  It can be dynamically extended at run-time using a `config` initialization handler.  Please see the Initialization documentation for more information on handlers and initialization phases.
+ * The configuration module provides utilities for working with an application's configuration
+ * document (ConfigDocument).  This module uses `process.env` to import configuration variables
+ * from the command-line build process.  It can be dynamically extended at run-time using a
+ * `config` initialization handler.  Please see the Initialization documentation for more
+ * information on handlers and initialization phases.
  *
  * @module Config
  */
@@ -32,7 +36,9 @@ let config = {
 };
 
 /**
- * Getter for the application configuration document.  This is synchronous and merely returns a reference to an existing object, and is thus safe to call as often as desired.  The document should have the following keys at a minimum:
+ * Getter for the application configuration document.  This is synchronous and merely returns a
+ * reference to an existing object, and is thus safe to call as often as desired.  The document
+ * should have the following keys at a minimum:
  *
  * @memberof Config
  * @returns {ConfigDocument}
@@ -44,7 +50,8 @@ export function getConfig() {
 /**
  * Replaces the existing ConfigDocument.  This is not commonly used, but can be helpful for tests.
  *
- * The supplied config document will be tested with `ensureDefinedConfig` to ensure it does not have any `undefined` keys.
+ * The supplied config document will be tested with `ensureDefinedConfig` to ensure it does not
+ * have any `undefined` keys.
  *
  * @memberof Config
  * @param {ConfigDocument} newConfig
@@ -56,7 +63,8 @@ export function setConfig(newConfig) {
 }
 
 /**
- * Merges additional configuration values into the ConfigDocument returned by `getConfig`.  Will override any values that exist with the same keys.
+ * Merges additional configuration values into the ConfigDocument returned by `getConfig`.  Will
+ * override any values that exist with the same keys.
  *
  * ```
  * mergeConfig({
@@ -76,7 +84,12 @@ export function mergeConfig(newConfig) {
 }
 
 /**
- * A method allowing application code to indicate that particular ConfigDocument keys are required for them to function.  This is useful for diagnosing development/deployment issues, primarily, by surfacing misconfigurations early.  For instance, if the build process fails to supply an environment variable on the command-line, it's possible that one of the `process.env` variables will be undefined.  Should be used in conjunction with `mergeConfig` for custom `ConfigDocument` properties.  Requester is for informational/error reporting purposes only.
+ * A method allowing application code to indicate that particular ConfigDocument keys are required
+ * for them to function.  This is useful for diagnosing development/deployment issues, primarily,
+ * by surfacing misconfigurations early.  For instance, if the build process fails to supply an
+ * environment variable on the command-line, it's possible that one of the `process.env` variables
+ * will be undefined.  Should be used in conjunction with `mergeConfig` for custom `ConfigDocument`
+ * properties.  Requester is for informational/error reporting purposes only.
  *
  * ```
  * ensureConfig(['LMS_BASE_URL', 'LOGIN_URL'], 'MySpecialComponent');
@@ -86,7 +99,10 @@ export function mergeConfig(newConfig) {
  * // if LOGIN_URL is undefined, for example.
  * ```
  *
- * *NOTE*: `ensureConfig` waits until `APP_CONFIG_INITIALIZED` is published to verify the existence of the specified properties.  This means that this function is compatible with custom `config` phase handlers responsible for loading additional configuration data in the initialization sequence.
+ * *NOTE*: `ensureConfig` waits until `APP_CONFIG_INITIALIZED` is published to verify the existence
+ * of the specified properties.  This means that this function is compatible with custom `config`
+ * phase handlers responsible for loading additional configuration data in the initialization
+ * sequence.
  *
  * @memberof Config
  * @param {Array} keys
@@ -114,7 +130,9 @@ export function ensureConfig(keys, requester = 'unspecified application code') {
  * }
  * ```
  *
- * When using Webpack (i.e., normal usage), the build process is responsible for supplying these variables via command-line environment variables.  That means they must be supplied at build time.
+ * When using Webpack (i.e., normal usage), the build process is responsible for supplying these
+ * variables via command-line environment variables.  That means they must be supplied at build
+ * time.
  *
  * @name ConfigDocument
  * @property {string} ACCESS_TOKEN_COOKIE_NAME

src/initialize.js

@@ -1,5 +1,6 @@
 /**
- * The initialization module provides a function for managing an application's initialization lifecycle.  It also provides constants and default handler implementations.
+ * The initialization module provides a function for managing an application's initialization
+ * lifecycle.  It also provides constants and default handler implementations.
  *
  * @module Initialization
  */
@@ -27,7 +28,9 @@ export const APP_READY = `${APP_TOPIC}.READY`;
 export const APP_INIT_ERROR = `${APP_TOPIC}.INIT_ERROR`;
 
 /**
- * A browser history object created by the [history](https://github.com/ReactTraining/history) package.  Applications are encouraged to use this history object, rather than creating their own, as behavior may be undefined when managing history via multiple mechanisms/instances.
+ * A browser history object created by the [history](https://github.com/ReactTraining/history)
+ * package.  Applications are encouraged to use this history object, rather than creating their own,
+ * as behavior may be undefined when managing history via multiple mechanisms/instances.
  *
  * @memberof Utilities
  */
@@ -48,10 +51,12 @@ export async function initError(error) {
  * The handler has several responsibilities:
  * - Determining the user's authentication state (authenticated or anonymous)
  * - Optionally redirecting to login if the application requires an authenticated user.
- * - Optionally loading additional user information via the application's user account data endpoint.
+ * - Optionally loading additional user information via the application's user account data
+ * endpoint.
  *
  * @memberof Initialization
- * @param {boolean} requireUser Whether or not we should redirect to login if a user is not authenticated.
+ * @param {boolean} requireUser Whether or not we should redirect to login if a user is not
+ * authenticated.
  * @param {boolean} hydrateUser Whether or not we should fetch additional user account data.
  */
 export async function auth(requireUser, hydrateUser) {
@@ -73,7 +78,9 @@ export async function auth(requireUser, hydrateUser) {
 /**
  * The default handler for the initialization lifecycle's `analytics` phase.
  *
- * The handler is responsible for identifying authenticated and anonymous users with the analytics service.  This is a pre-requisite for sending analytics events, thus, we do it during the initialization sequence so that analytics is ready once the application's UI code starts to load.
+ * The handler is responsible for identifying authenticated and anonymous users with the analytics
+ * service.  This is a pre-requisite for sending analytics events, thus, we do it during the
+ * initialization sequence so that analytics is ready once the application's UI code starts to load.
  *
  * @memberof Initialization
  */
@@ -107,12 +114,23 @@ function applyOverrideHandlers(overrides) {
  *
  * @memberof Initialization
  * @param {Object} [options]
- * @param {*} [options.loggingService=NewRelicLoggingService] The `LoggingService` implementation to use.
- * @param {*} [options.analyticsService=SegmentAnalyticsService] The `AnalyticsService` implementation to use.
- * @param {*} [options.requireAuthenticatedUser=false] If true, turns on automatic login redirection for unauthenticated users.  Defaults to false, meaning that by default the application will allow anonymous/unauthenticated sessions.
- * @param {*} [options.hydrateAuthenticatedUser=false] If true, makes an API call to the user account endpoint (`${App.config.LMS_BASE_URL}/api/user/v1/accounts/${username}`) to fetch detailed account information for the authenticated user. This data is merged into the return value of `getAuthenticatedUser`, overriding any duplicate keys that already exist. Defaults to false, meaning that no additional account information will be loaded.
- * @param {*} [options.messages] A i18n-compatible messages object, or an array of such objects. If an array is provided, duplicate keys are resolved with the last-one-in winning.
- * @param {*} [options.handlers={}] An optional object of handlers which can be used to replace the default behavior of any part of the startup sequence. It can also be used to add additional  initialization behavior before or after the rest of the sequence.
+ * @param {*} [options.loggingService=NewRelicLoggingService] The `LoggingService` implementation
+ * to use.
+ * @param {*} [options.analyticsService=SegmentAnalyticsService] The `AnalyticsService`
+ * implementation to use.
+ * @param {*} [options.requireAuthenticatedUser=false] If true, turns on automatic login
+ * redirection for unauthenticated users.  Defaults to false, meaning that by default the
+ * application will allow anonymous/unauthenticated sessions.
+ * @param {*} [options.hydrateAuthenticatedUser=false] If true, makes an API call to the user
+ * account endpoint (`${App.config.LMS_BASE_URL}/api/user/v1/accounts/${username}`) to fetch
+ * detailed account information for the authenticated user. This data is merged into the return
+ * value of `getAuthenticatedUser`, overriding any duplicate keys that already exist. Defaults to
+ * false, meaning that no additional account information will be loaded.
+ * @param {*} [options.messages] A i18n-compatible messages object, or an array of such objects. If
+ * an array is provided, duplicate keys are resolved with the last-one-in winning.
+ * @param {*} [options.handlers={}] An optional object of handlers which can be used to replace the
+ * default behavior of any part of the startup sequence. It can also be used to add additional
+ * initialization behavior before or after the rest of the sequence.
  */
 export async function initialize({
   loggingService = NewRelicLoggingService,

src/pubSub.js

@@ -1,9 +1,16 @@
 /**
- * The PubSub module is a thin wrapper around the base functionality of [PubSubJS](https://github.com/mroderick/PubSubJS).  For the sake of simplicity and not relying too heavily on implementation-specific features, it maintains a fairly simple API (subscribe, unsubscribe, and publish).
+ * The PubSub module is a thin wrapper around the base functionality of
+ * [PubSubJS](https://github.com/mroderick/PubSubJS).  For the sake of simplicity and not relying
+ * too heavily on implementation-specific features, it maintains a fairly simple API (subscribe,
+ * unsubscribe, and publish).
  *
- * Publish/Subscribe events should be used mindfully, especially in relation to application UI frameworks like React.  Given React's unidirectional data flow and prop/state management capabilities, using a pub/sub mechanism is at odds with that framework's best practices.
+ * Publish/Subscribe events should be used mindfully, especially in relation to application UI
+ * frameworks like React.  Given React's unidirectional data flow and prop/state management
+ * capabilities, using a pub/sub mechanism is at odds with that framework's best practices.
  *
- * That said, we use pub/sub in our application initialization sequence to allow applications to hook into the initialization lifecycle, and we also use them to publish when the application state has changed, i.e., when the config document or user's authentication state have changed.
+ * That said, we use pub/sub in our application initialization sequence to allow applications to
+ * hook into the initialization lifecycle, and we also use them to publish when the application
+ * state has changed, i.e., when the config document or user's authentication state have changed.
  *
  * @module PubSub
  */

src/utils.js

@@ -6,9 +6,11 @@ import camelCase from 'lodash.camelcase';
 import snakeCase from 'lodash.snakecase';
 
 /**
- * This is the underlying function used by camelCaseObject, snakeCaseObject, and convertKeyNames above.
+ * This is the underlying function used by camelCaseObject, snakeCaseObject, and convertKeyNames
+ * above.
  *
- * Given an object (or array) and a modification function, will perform the function on each key it encounters on the object and its tree of children.
+ * Given an object (or array) and a modification function, will perform the function on each key it
+ * encounters on the object and its tree of children.
  *
  * The modification function must take a string as an argument and returns a string.
  *
@@ -23,9 +25,11 @@ import snakeCase from 'lodash.snakecase';
  * }
  * ```
  *
- * This function will turn any key that matches 'edX' into 'Open edX'.  All other keys will be passed through unmodified.
+ * This function will turn any key that matches 'edX' into 'Open edX'.  All other keys will be
+ * passed through unmodified.
  *
- * Can accept arrays as well as objects, and will perform its conversion on any objects it finds in the array.
+ * Can accept arrays as well as objects, and will perform its conversion on any objects it finds in
+ * the array.
  *
  * @memberof Utilities
  * @param {Object} object
@@ -55,9 +59,13 @@ export function modifyObjectKeys(object, modify) {
 }
 
 /**
- * Performs a deep conversion to camelCase on all keys in the provided object and its tree of  children.  Uses [lodash.camelcase](https://lodash.com/docs/4.17.15#camelCase) on each key.  This is commonly used to convert snake_case keys in models from a backend server into camelCase keys for use in the JavaScript client.
+ * Performs a deep conversion to camelCase on all keys in the provided object and its tree of
+ * children.  Uses [lodash.camelcase](https://lodash.com/docs/4.17.15#camelCase) on each key.  This
+ * is commonly used to convert snake_case keys in models from a backend server into camelCase keys
+ * for use in the JavaScript client.
  *
- * Can accept arrays as well as objects, and will perform its conversion on any objects it finds in the array.
+ * Can accept arrays as well as objects, and will perform its conversion on any objects it finds in
+ * the array.
  *
  * @memberof Utilities
  * @param {Array|Object} object
@@ -68,9 +76,13 @@ export function camelCaseObject(object) {
 }
 
 /**
- * Performs a deep conversion to snake_case on all keys in the provided object and its tree of children.  Uses [lodash.snakecase](https://lodash.com/docs/4.17.15#snakeCase) on each key.  This is commonly used to convert camelCase keys from the JavaScript app into snake_case keys expected by backend servers.
+ * Performs a deep conversion to snake_case on all keys in the provided object and its tree of
+ * children.  Uses [lodash.snakecase](https://lodash.com/docs/4.17.15#snakeCase) on each key.  This
+ * is commonly used to convert camelCase keys from the JavaScript app into snake_case keys expected
+ * by backend servers.
  *
- * Can accept arrays as well as objects, and will perform its conversion on any objects it finds in the array.
+ * Can accept arrays as well as objects, and will perform its conversion on any objects it finds in
+ * the array.
  *
  * @memberof Utilities
  * @param {Array|Object} object
@@ -81,7 +93,10 @@ export function snakeCaseObject(object) {
 }
 
 /**
- * Given a map of key-value pairs, performs a deep conversion key names in the specified object _from_ the key _to_ the value.  This is useful for updating names in an API request to the names used throughout a client application if they happen to differ.  It can also be used in the reverse - formatting names from the client application to names expected by an API.
+ * Given a map of key-value pairs, performs a deep conversion key names in the specified object
+ * _from_ the key _to_ the value.  This is useful for updating names in an API request to the names
+ * used throughout a client application if they happen to differ.  It can also be used in the
+ * reverse - formatting names from the client application to names expected by an API.
  *
  * ```
  * import { convertKeyNames } from '@edx/frontend-base';
@@ -96,7 +111,8 @@ export function snakeCaseObject(object) {
  * console.log(result) // { their_key: 'my value' }
  * ```
  *
- * Can accept arrays as well as objects, and will perform its conversion on any objects it finds in the array.
+ * Can accept arrays as well as objects, and will perform its conversion on any objects it finds in
+ * the array.
  *
  * @memberof Utilities
  * @param {Array|Object} object
@@ -112,7 +128,8 @@ export function convertKeyNames(object, nameMap) {
 
 /**
  * *Deprecated*: A method which converts the supplied query string into an object of
-key-value pairs and returns it.  Defaults to the current query string - should perform like [window.searchParams](https://developer.mozilla.org/en-US/docs/Web/API/URL/searchParams)
+ * key-value pairs and returns it.  Defaults to the current query string - should perform like
+ * [window.searchParams](https://developer.mozilla.org/en-US/docs/Web/API/URL/searchParams)
  *
  * @deprecated
  * @memberof Utilities