Merge pull request #429 from Mallikki/feature/documentation

docs(stark-all): improve Stark documentation

.travis.yml

@@ -48,6 +48,7 @@ cache:
 script:
   - npm run lint:all
   - npm run test:ci:all
+  - npm run docs:coverage
   - npm run build:showcase
   - npm run docs:publish
   - npm run release:publish

docs/ENVIRONMENTS.md

@@ -1,4 +1,4 @@
-# Environments support 
+# Environments support
 
 ## Environment.ts
 
@@ -12,10 +12,11 @@ export interface Environment {
 	...
 ```
 
-`production`, which is a boolean, will specify is your application runs under a production environment, 
-while `hmr` will indicate if it runs under a Hot Module Replacement environment. 
+`production`, which is a boolean, will specify is your application runs under a production environment,
+while `hmr` will indicate if it runs under a Hot Module Replacement environment.
+
+This interface will then be defined by default in `src/environments/environment.ts`:
 
-This interface will then be defined by default in `src/environments/environment.ts`: 
 ```
 ...
 export const environment: Environment = {
@@ -25,41 +26,42 @@ export const environment: Environment = {
 	...
 ```
 
-## How to find out which environment is your application is currently using? 
+## How to find out which environment is your application is currently using?
+
+All you have to do is to import the environment.ts constant anywhere you want in your application:
 
-All you have to do is to import the environment.ts constant anywhere you want in your application: 
 ```
 import { environment } from "environments/environment";
 ```
 
 This way, you will be able to programmatically determine which environment is used in your app
-with simple checks, as follows: 
+with simple checks, as follows:
 
 ```
-environment.production 
-// if the output of this line is true, we are in production environment. 
-// Otherwise, we are in hmr environment. 
+environment.production
+// if the output of this line is true, we are in production environment.
+// Otherwise, we are in hmr environment.
 ```
 
 ## How to add a new environment ?
 
-First, create you new Ts file in the `src/environments` folder. 
+First, create you new Ts file in the `src/environments` folder.
 
 Then, make sure your new environment extends the `src/environments/model.ts` interface.
 
-Finally, define the options and file replacement of your new environment in the `angular.json` file. 
+Finally, define the options and file replacement of your new environment in the `angular.json` file.
 
-For exemple, the environment.dummyEnv.ts file: 
+For exemple, the environment.dummyEnv.ts file:
 
-````
+```
 import { enableProdMode, NgModuleRef } from "@angular/core";
 import { disableDebugTools } from "@angular/platform-browser";
 import { Environment } from "./model";
 
 enableProdMode();
 
-export const environment: Environment = { 
-	
+export const environment: Environment = {
+
 	production: false,
 	hmr: false,
 
@@ -69,11 +71,11 @@ export const environment: Environment = {
 	},
 	ENV_PROVIDERS: []
 }
-````
+```
 
-And in the angular.json file: 
+And in the angular.json file:
 
-````
+```
  "dummyEnv" : {
     "fileReplacements": [
       {
@@ -82,4 +84,4 @@ And in the angular.json file:
       }
     ]
   }
-````
+```

package.json

@@ -87,7 +87,7 @@
     "commit": "./node_modules/.bin/git-cz",
     "commitmsg": "commitlint -e $GIT_PARAMS",
     "docs": "npm run docs:clean && npm run docs:all",
-    "docs:all": "npm run docs:stark-core:generate && npm run docs:stark-ui:generate",
+    "docs:all": "npm run docs:stark-core:generate && npm run docs:stark-ui:generate && npm run docs:starter:generate",
     "docs:clean": "npx rimraf reports/api-docs",
     "docs:coverage": "npm run docs:stark-core:coverage && npm run docs:stark-ui:coverage && npm run docs:starter:coverage",
     "docs:publish": "bash ./gh-deploy.sh --trace",
@@ -124,7 +124,7 @@
     "install:ci:starter": "cd starter && npm ci && cd ..",
     "install:travis:all": "npm run install:stark-build && npm run install:stark-testing && npm run install:stark-core && npm run install:stark-ui && npm run build:trace && npm run update:starter && npm run update:showcase",
     "ngc": "ngc",
-    "precommit": "lint-staged",
+    "precommit": "lint-staged && npm run docs:coverage",
     "prettier-check": "prettier **/*.{css,js,json,md,pcss,scss,ts} --write",
     "preupdate:showcase": "npm run clean:showcase",
     "preupdate:starter": "npm run clean:starter",

packages/stark-build/config/build-utils.js

@@ -39,13 +39,12 @@ function readTsConfig(tsConfigPath) {
 }
 
 /**
- * Method which returns the path of the environment file of the received environment.
  * The method reads the content of angular.json for getting the path (read with value or replace in "fileReplacements" of environment.
  *
  * See: https://github.com/angular/angular-cli/wiki/angular-workspace
  *
  * @param environment
- * @returns {*}
+ * @returns {*} - the path of the environment file of the received environment.
  */
 function getEnvironmentFile(environment) {
 	if (typeof environment === "string") {

packages/stark-build/config/helpers.js

@@ -24,7 +24,7 @@ function isWebpackDevServer() {
 /**
  * Retrieve the relative path from the config directory to the path argument value (if provided). That path argument can be passed to only execute a subset of the unit tests (see spec-bundle.ts)
  * @param args the arguments to look into
- * @returns {*} The relative path from this directory (config) to the location pointed at by the path argument value (if provided), an empty string otherwise
+ * @returns The relative path from this directory (config) to the location pointed at by the path argument value (if provided), an empty string otherwise
  */
 function getTestPath(args) {
 	for (let i = 0; i < args.length; ++i) {

packages/stark-build/config/json-server.common.js

@@ -47,7 +47,7 @@ const starkMetadata = {
  * @param middlewares {object} Middlewares to be applied just after the default Stark middlewares
  * @param routes {object} (Optional) Routes to be rewritten (in order to support nested resources)
  * @param uploadEndpoints {object} (Optional) Endpoints for file uploads
- * @returns {server} ExpressJS server definition
+ * @returns ExpressJS server definition
  */
 function getJSONServer(data, middlewares, routes, uploadEndpoints) {
 	var server = jsonServer.create();
@@ -176,8 +176,6 @@ function transformRequests(req, res, next) {
  * - Request: the current request
  * - Response: the current response (containing the default changes made by Stark middleware)
  * - StarkMetadata: metadata object constructed by the Stark middleware (only for Collection responses)
- *
- * @returns {Function}
  */
 function composeTransformResponses(transformFn) {
 	return function(req, res) {
@@ -205,7 +203,7 @@ function composeTransformResponses(transformFn) {
  * Default Stark response transformations: metadata and etags
  * @param req {*} The current request (already changed by Stark default middleware)
  * @param res {*} The current response (already changed by Stark default middleware)
- * @param collectionMetadata {object} Metadata object constructed by the Stark middleware (only for Collection responses)
+ * @param collectionMetadata : Metadata object constructed by the Stark middleware (only for Collection responses)
  */
 function transformResponses(req, res, collectionMetadata) {
 	console.log("transformResponses Stark middleware");
@@ -238,8 +236,8 @@ function transformResponses(req, res, collectionMetadata) {
 
 /**
  * Extract the query parameters from the request url
- * @param url {string} Request url
- * @returns {object} Object containing the different query parameters
+ * @param url: Request url
+ * @returns Object containing the different query parameters
  */
 function extractUrlParams(url) {
 	var queryParams = {};
@@ -260,7 +258,7 @@ function extractUrlParams(url) {
 
 /**
  * Replace Stark pagination params by JSON-server pagination params
- * @param req {*} The current request
+ * @param req : The current request
  */
 function transformPaginationParams(req) {
 	const limit = parseInt(req.query[starkQueryParam.LIMIT], 10) || 10; // defaults to 10
@@ -276,7 +274,7 @@ function transformPaginationParams(req) {
 
 /**
  * Replace Stark sorting params by JSON-server sorting params
- * @param req {*} The current request
+ * @param req : The current request
  */
 function transformSortingParams(req) {
 	const sortingRegex = /(\w+)\+(ASC|DESC)/g; // perform a global search to match all the sort items
@@ -301,7 +299,7 @@ function transformSortingParams(req) {
 
 /**
  * Change POST requests to PATCH for an existing resource (when the uuid is defined)
- * @param req {*} The current request
+ * @param req : The current request
  */
 function convertUpdateRequestMethod(req) {
 	if (req.method === "POST" && req.body && req.body.uuid) {
@@ -312,9 +310,9 @@ function convertUpdateRequestMethod(req) {
 /**
  * Add "pagination" object to metadata for Collection responses
  * See https://github.com/NationalBankBelgium/REST-API-Design-Guide/wiki/Pagination-Rules-and-metadata
- * @param req {*} The current request
- * @param res {*} The current response
- * @param collectionMetadata {object} Metadata object constructed by the Stark middleware (only for Collection responses)
+ * @param req : The current request
+ * @param res : The current response
+ * @param collectionMetadata : Metadata object constructed by the Stark middleware (only for Collection responses)
  */
 function addPaginationMetadata(req, res, collectionMetadata) {
 	var pagination = (collectionMetadata["pagination"] = {});
@@ -348,8 +346,8 @@ function addPaginationMetadata(req, res, collectionMetadata) {
 /**
  * In case the metadata object is passed, the "etags" object is added to it (Collection responses)
  * Otherwise the "etag" header is added to the response (single item responses)
- * @param res {*} The current request
- * @param collectionMetadata {object} Metadata object constructed by the Stark middleware (only for Collection responses)
+ * @param res : The current request
+ * @param collectionMetadata : Metadata object constructed by the Stark middleware (only for Collection responses)
  */
 function addEtagInfo(res, collectionMetadata) {
 	const data = res.locals.data;
@@ -400,8 +398,7 @@ function addSortingMetadata(req, collectionMetadata) {
  * Check whether the request is a GetCollection request.
  * GetCollection requests are the ones with a "mockCollectionRequest" query param.
  * See: https://jira.prd.nbb/browse/NG-1335
- * @param req {*} The current request
- * @returns {boolean}
+ * @param req : The current request
  */
 function isGetCollectionRequest(req) {
 	var params = extractUrlParams(req.originalUrl);
@@ -411,8 +408,7 @@ function isGetCollectionRequest(req) {
 /**
  * Check whether the request is aimed to get a nested resource (from a many-to-one relationship).
  * Such requests have a '_expand' query parameter
- * @param req {*} The current request
- * @returns {boolean}
+ * @param req : The current request
  */
 function isNestedResourceQuery(req) {
 	return req.method === "GET" && typeof req.query["_expand"] !== "undefined";
@@ -421,8 +417,7 @@ function isNestedResourceQuery(req) {
 /**
  * Get the name of the nested resource to be fetched in the request (from a many-to-one relationship).
  * Such resource is the one passed in the '_expand' query parameter.
- * @param req {*} The current request
- * @returns {string|undefined}
+ * @param req : The current request
  */
 function getNestedResourceName(req) {
 	return req.query["_expand"];
@@ -431,7 +426,6 @@ function getNestedResourceName(req) {
 /**
  * Generate an Etag random value
  * @param item
- * @returns {string}
  */
 function generateEtagValue(item) {
 	return _uniqueId(
@@ -469,8 +463,7 @@ function deepReplaceProperty(item, property, newProperty) {
 /**
  * Add to the original routes for nested resources (those that will be rewritten with a '_expand' query parameter)
  * with an optional query param regex so that the route can match regardless of whether it has or not query params
- * @param routes {object} Routes to be rewritten (in order to support nested resources)
- * @returns {object}
+ * @param routes : Routes to be rewritten (in order to support nested resources)
  */
 function expandRewrittenRoutes(routes) {
 	const nestedResourceRegex = /^\/(\w+)\/:(\w+)\/(\w+)$/;

packages/stark-core/package.json

@@ -60,7 +60,7 @@
     "clean:modules": "npx rimraf ./node_modules package-lock.json",
     "clean:all": "npm run clean && npm run clean:modules",
     "docs": "node ../../node_modules/@compodoc/compodoc/bin/index-cli src --theme material --tsconfig ../tsconfig.json --output ../../reports/api-docs/stark-core",
-    "docs:coverage": "npm run docs -- --coverageTest --coverageThresholdFail true",
+    "docs:coverage": "npm run docs -- --coverageTest 85 --coverageThresholdFail true",
     "docs:serve": "npm run docs -- --watch --serve --port 4321",
     "ngc": "node ../../node_modules/@angular/compiler-cli/src/main.js -p tsconfig-build.json",
     "lint": "node ../../node_modules/tslint/bin/tslint --config ./tslint.json --project ./tsconfig.spec.json --format codeFrame",

packages/stark-core/public_api.ts

@@ -1,6 +1,4 @@
 /**
- * @module
- * @description
  * Entry point for all public APIs of this package.
  */
 export * from "./src/stark-core";

packages/stark-core/src/common/error/error.ts

@@ -1,8 +1,11 @@
+/* tslint:disable:completed-docs*/
 import moment from "moment";
 import { autoserialize } from "cerialize";
 
 import { StarkError } from "./error.intf";
-
+/**
+ * @ignore
+ */
 export class StarkErrorImpl implements StarkError {
 	@autoserialize public message?: string;
 	@autoserialize public name?: string;

packages/stark-core/src/common/routes/routes.ts

@@ -2,23 +2,52 @@ import { Location } from "@angular/common";
 import { STARK_ROUTING_SERVICE, StarkRoutingService, StarkStateConfigWithParams } from "../../modules/routing/services";
 import { StatesModule } from "@uirouter/angular";
 
+/**
+ * Name of the initialization states of the application
+ */
 export const starkAppInitStateName: string = "starkAppInit";
+/**
+ * Name of the exit states of the application
+ */
 export const starkAppExitStateName: string = "starkAppExit";
-
+/**
+ * Name of the login state of the application
+ */
 export const starkLoginStateName: string = "starkAppInit.starkLogin";
+/**
+ * URL of the login state of the application
+ */
 export const starkLoginStateUrl: string = "/starkLogin";
-
+/**
+ * Name of the preloading state of the application
+ */
 export const starkPreloadingStateName: string = "starkAppInit.starkPreloading";
+/**
+ * URL of the preloading state of the application
+ */
 export const starkPreloadingStateUrl: string = "/starkPreloading";
-
+/**
+ * Name of the SessionExpired state of the application
+ */
 export const starkSessionExpiredStateName: string = "starkAppExit.starkSessionExpired";
+/**
+ * URL of the SessionExpired state of the application
+ */
 export const starkSessionExpiredStateUrl: string = "/starkSessionExpired";
-
+/**
+ * Name of the SessionLogout state of the application
+ */
 export const starkSessionLogoutStateName: string = "starkAppExit.starkSessionLogout";
+/**
+ * URL of the SessionLogout state of the application
+ */
 export const starkSessionLogoutStateUrl: string = "/starkSessionLogout";
 
 // FIXME Fix states declaration
 /* tslint:disable:no-duplicate-string */
+/**
+ * Configuration of the route state of the application
+ */
 export const starkCoreRouteConfig: StatesModule = <any>{
 	states: [
 		{

packages/stark-core/src/common/store/stark-core-application-state.ts

@@ -1,10 +1,9 @@
-/**
- * Interface defining the shape of the application state of Stark Core (i.e., what's stored in Redux by Stark)
- */
 import { StarkLoggingState } from "../../modules/logging/reducers";
 import { StarkSessionState } from "../../modules/session/reducers";
 import { StarkSettingsState } from "../../modules/settings/reducers";
-
+/**
+ * Interface defining the shape of the application state of Stark Core (i.e., what's stored in Redux by Stark)
+ */
 export interface StarkCoreApplicationState extends StarkLoggingState, StarkSessionState, StarkSettingsState {
 	// FIXME: still needed?
 	// starkApplicationMetadata: StarkApplicationMetadata;

packages/stark-core/src/common/translations/locale.intf.ts

@@ -1,4 +1,14 @@
+/**
+ * Contains the translation for a specific language
+ */
 export interface StarkLocale {
+	/**
+	 * The code of the language that we want to retrieve
+	 */
 	languageCode: string;
+
+	/**
+	 * The actual translation of the text
+	 */
 	translations: Object;
 }