update commnts

ts/npmci.build.docker.ts

@@ -3,6 +3,9 @@ import * as paths from "./npmci.paths";
 import * as NpmciEnv from "./npmci.env";
 import {bashBare} from "./npmci.bash";
 
+/**
+ * builds a cwd of Dockerfiles by triggering a promisechain
+ */
 export let build = function(){
     let done = plugins.q.defer();
     readDockerfiles()
@@ -16,8 +19,12 @@ export let build = function(){
     return done.promise;
 }
 
-export let readDockerfiles = function(){
-    let done = plugins.q.defer();
+/**
+ * creates instance of class Dockerfile for all Dockerfiles in cwd
+ * @returns Promise<Dockerfile[]>
+ */
+export let readDockerfiles = function():plugins.q.Promise<Dockerfile[]>{
+    let done = plugins.q.defer<Dockerfile[]>();
     let readDockerfilesArray:Dockerfile[] = []
     plugins.gulp.src("./Dockerfile*")
         .pipe(plugins.through2.obj(function(file,enc,cb){
@@ -33,8 +40,13 @@ export let readDockerfiles = function(){
     return done.promise;
 }
 
-export let sortDockerfiles = function(sortableArrayArg:Dockerfile[]){
-    let done = plugins.q.defer();
+/**
+ * sorts Dockerfiles into a dependency chain
+ * @param sortableArrayArg an array of instances of class Dockerfile
+ * @returns Promise<Dockerfile[]>
+ */
+export let sortDockerfiles = function(sortableArrayArg:Dockerfile[]):plugins.q.Promise<Dockerfile[]>{
+    let done = plugins.q.defer<Dockerfile[]>();
     let sortedArray:Dockerfile[] = [];
     let cleanTagsOriginal = cleanTagsArrayFunction(sortableArrayArg,sortedArray);
     let sorterFunctionCounter:number = 0;
@@ -59,8 +71,11 @@ export let sortDockerfiles = function(sortableArrayArg:Dockerfile[]){
     return done.promise;
 };
 
-export let mapDockerfiles = function(sortedArray:Dockerfile[]){
-    let done = plugins.q.defer();
+/**
+ * maps local Dockerfiles dependencies to the correspoding Dockerfile class instances
+ */
+export let mapDockerfiles = function(sortedArray:Dockerfile[]):plugins.q.Promise<Dockerfile[]>{
+    let done = plugins.q.defer<Dockerfile[]>();
     sortedArray.forEach((dockerfileArg) => {
         if(dockerfileArg.localBaseImageDependent){
             sortedArray.forEach((dockfile2:Dockerfile) => {
@@ -74,6 +89,9 @@ export let mapDockerfiles = function(sortedArray:Dockerfile[]){
     return done.promise;
 }
 
+/**
+ * builds the correspoding real docker image for each Dockerfile class instance
+ */
 export let buildDockerfiles = (sortedArrayArg:Dockerfile[]) => {
     let done = plugins.q.defer();
     sortedArrayArg.forEach(function(dockerfileArg){
@@ -83,6 +101,9 @@ export let buildDockerfiles = (sortedArrayArg:Dockerfile[]) => {
     return done.promise;
 }
 
+/**
+ * pushes the real Dockerfile images to a Docker registry
+ */
 export let pushDockerfiles = function(sortedArrayArg:Dockerfile[]){
     let done = plugins.q.defer();
     sortedArrayArg.forEach(function(dockerfileArg){
@@ -92,6 +113,10 @@ export let pushDockerfiles = function(sortedArrayArg:Dockerfile[]){
     return done.promise;
 }
 
+/**
+ * pulls corresponding real Docker images for instances of Dockerfile from a registry.
+ * This is needed if building, testing, and publishing of Docker images is carried out in seperate CI stages.
+ */
 export let pullDockerfileImages = (sortableArrayArg:Dockerfile[],registryArg = "registry.gitlab.com") => {
     let done = plugins.q.defer();
     sortableArrayArg.forEach((dockerfileArg) => {
@@ -101,6 +126,10 @@ export let pullDockerfileImages = (sortableArrayArg:Dockerfile[],registryArg = "
     return done.promise;
 }
 
+/**
+ * tests all Dockerfiles in by calling class Dockerfile.test();
+ * @param sortedArrayArg Dockerfile[] that contains all Dockerfiles in cwd
+ */
 export let testDockerfiles = (sortedArrayArg:Dockerfile[]) => {
     let done = plugins.q.defer();
     sortedArrayArg.forEach(function(dockerfileArg){
@@ -110,6 +139,9 @@ export let testDockerfiles = (sortedArrayArg:Dockerfile[]) => {
     return done.promise;
 };
 
+/**
+ * class Dockerfile represents a Dockerfile on disk in npmci
+ */
 export class Dockerfile {
     filePath:string;
     repo:string;
@@ -138,6 +170,10 @@ export class Dockerfile {
         this.baseImage = dockerBaseImage(this.content);
         this.localBaseImageDependent = false;
     };
+
+    /**
+     * builds the Dockerfile
+     */
     build(){
         let done = plugins.q.defer();
         plugins.beautylog.info("now building Dockerfile for " + this.cleanTag);
@@ -146,6 +182,10 @@ export class Dockerfile {
         done.resolve();
         return done.promise;
     };
+
+    /**
+     * pushes the Dockerfile to a registry
+     */
     push(stageArg){
         let done = plugins.q.defer();
         let pushTag;
@@ -162,12 +202,20 @@ export class Dockerfile {
         bashBare("docker push " + pushTag);
         done.resolve();
         return done.promise;
-    }
+    };
+
+    /**
+     * pulls the Dockerfile from a registry
+     */
     pull(registryArg:string){
         let pullTag = this.testTag;
         bashBare("docker pull " + pullTag);
         bashBare("docker tag " + pullTag + " " + this.buildTag);
     };
+
+    /**
+     * tests the Dockerfile;
+     */
     test(){
         let testFile:string = plugins.path.join(paths.NpmciTestDir,"test_" + this.version + ".sh");
         let testFileExists:boolean = plugins.smartfile.fs.fileExistsSync(testFile);
@@ -182,12 +230,19 @@ export class Dockerfile {
             plugins.beautylog.warn("skipping tests for " + this.cleanTag + " because no testfile was found!");
         }
     };
+
+    /**
+     * gets the id of a Dockerfile
+     */
     getId(){
         let containerId = bashBare("docker inspect --type=image --format=\"{{.Id}}\" " + this.buildTag);
         return containerId;
     };
 }
 
+/**
+ * 
+ */
 export let dockerFileVersion = function(dockerfileNameArg:string):string{
     let versionString:string;
     let versionRegex = /Dockerfile_([a-zA-Z0-9\.]*)$/;
@@ -200,12 +255,18 @@ export let dockerFileVersion = function(dockerfileNameArg:string):string{
     return versionString;
 }
 
+/**
+ * 
+ */
 export let dockerBaseImage = function(dockerfileContentArg:string){
     let baseImageRegex = /FROM\s([a-zA-z0-9\/\-\:]*)\n?/
     let regexResultArray = baseImageRegex.exec(dockerfileContentArg)
     return regexResultArray[1];
 }
 
+/**
+ * 
+ */
 export let dockerTag = function(registryArg:string,repoArg:string,versionArg:string,suffixArg?:string):string{
     let tagString:string;
     let registry = registryArg;
@@ -218,6 +279,9 @@ export let dockerTag = function(registryArg:string,repoArg:string,versionArg:str
     return tagString;
 };
 
+/**
+ * 
+ */
 export let cleanTagsArrayFunction = function(dockerfileArrayArg:Dockerfile[],trackingArrayArg:Dockerfile[]):string[]{
     let cleanTagsArray:string[] = [];
     dockerfileArrayArg.forEach(function(dockerfileArg){