refactoring + library documentation with typedoc #58

index.ts

@@ -25,7 +25,7 @@
 import { NgModule, ModuleWithProviders } from '@angular/core';
 import { AngularModalGalleryModule } from './src/modal-gallery.module';
 
-export { Image, ImageModalEvent, Action, Description, ButtonsConfig, KeyboardConfig } from './src/components/modal-gallery';
+export { Image, ImageModalEvent, Action, Description, ButtonsConfig, KeyboardConfig } from './src/components/modal-gallery.component';
 
 @NgModule({
   imports: [

src/components/gallery.component.ts

@@ -24,7 +24,7 @@
  */
 
 import {Input, Output, EventEmitter, Component} from '@angular/core';
-import {Image} from "./modal-gallery";
+import {Image} from "./modal-gallery.component";
 
 @Component({
   selector: 'gallery',

src/components/modal-gallery.ts → src/components/modal-gallery.component.ts

@@ -16,7 +16,7 @@
 
  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
- FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ FITNESS FOR A PARTICULAR PURPOSE AND NON INFRINGEMENT. IN NO EVENT SHALL THE
  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
@@ -190,6 +190,9 @@ export class AngularModalGallery implements OnInit, OnDestroy, OnChanges {
     this.description.beforeTextDescription = this.description.beforeTextDescription || ' - ';
   }
 
+  /**
+   * Method ´ngOnInit´ to build `configButtons` and to call `initImages()`
+   */
   ngOnInit() {
     // build configButtons to use it inside upper-buttons
     this.configButtons = {
@@ -201,6 +204,10 @@ export class AngularModalGallery implements OnInit, OnDestroy, OnChanges {
     this.initImages();
   }
 
+  /**
+   * Private method ´initImages´ to initialize `images` as array of `Image` or as an Observable of `Array<Image>`.
+   * Also, it will call completeInitialization.
+   */
   private initImages() {
     if (this.modalImages instanceof Array) {
       this.images = this.modalImages;
@@ -215,6 +222,10 @@ export class AngularModalGallery implements OnInit, OnDestroy, OnChanges {
     }
   }
 
+  /**
+   * Private method ´completeInitialization´ to emit ImageModalEvent to say that images are loaded. If you are
+   * using imagePointer feature, it will also call showModalGallery with imagePointer as parameter.
+   */
   private completeInitialization() {
     this.hasData.emit(new ImageModalEvent(Action.LOAD, true));
     this.loading = true;
@@ -226,6 +237,9 @@ export class AngularModalGallery implements OnInit, OnDestroy, OnChanges {
     }
   }
 
+  /**
+   * Method ´ngOnChanges´ to init images preventing errors.
+   */
   ngOnChanges(changes: SimpleChanges) {
     // to prevent errors when you pass to this library
     // the array of images inside a subscribe block, in this way: `...subscribe(val => { this.images = arrayOfImages })`
@@ -235,6 +249,12 @@ export class AngularModalGallery implements OnInit, OnDestroy, OnChanges {
     }
   }
 
+  /**
+   * Method `getDescriptionToDisplay` to get the image description based on input params.
+   * If you provide a full description this will be the visible description, otherwise,
+   *  it will be built using the `description` object, concatenating fields.
+   * @returns {string} the description to display
+   */
   getDescriptionToDisplay() {
     if (this.description && this.description.customFullDescription) {
       return this.description.customFullDescription;
@@ -247,7 +267,11 @@ export class AngularModalGallery implements OnInit, OnDestroy, OnChanges {
     return `${this.description.imageText}${this.currentImageIndex + 1}${this.description.numberSeparator}${this.images.length}${this.description.beforeTextDescription}${this.currentImage.description}`;
   }
 
-  // hammerjs touch gestures support
+  /**
+   * Method `swipe` used by hammerjs to support touch gestures.
+   * @param index Number that represent the current visible index
+   * @param action String that represent the direction of the swipe action. 'swiperight' by default.
+   */
   swipe(index: number, action = this.SWIPE_ACTION.RIGHT) {
     switch (action) {
       case this.SWIPE_ACTION.RIGHT:
@@ -263,28 +287,55 @@ export class AngularModalGallery implements OnInit, OnDestroy, OnChanges {
     }
   }
 
+  /**
+   * Method `closeGallery` to close the modal gallery.
+   * @param action Enum of type `Action` that represents the source
+   *  action that closed the modal gallery. NORMAL by default.
+   */
   closeGallery(action: Action = Action.NORMAL) {
     this.close.emit(new ImageModalEvent(action, true));
     this.opened = false;
     this.keyboardService.reset();
   }
 
+  /**
+   * Method `prevImage` to go back to the previous image shown into the modal gallery.
+   * @param action Enum of type `Action` that represents the source
+   *  action that moved back to the previous image. NORMAL by default.
+   */
   prevImage(action: Action = Action.NORMAL) {
     this.loading = true;
     this.currentImageIndex = this.getPrevIndex(action, this.currentImageIndex);
     this.showModalGallery(this.currentImageIndex);
   }
 
+  /**
+   * Method `prevImage` to go back to the previous image shown into the modal gallery.
+   * @param action Enum of type `Action` that represents the source
+   *  action that moved to the next image. NORMAL by default.
+   */
   nextImage(action: Action = Action.NORMAL) {
     this.loading = true;
     this.currentImageIndex = this.getNextIndex(action, this.currentImageIndex);
     this.showModalGallery(this.currentImageIndex);
   }
 
+  /**
+   * Method `onShowModalGallery` called when you click on an image of your gallery.
+   * The input index is the index of the clicked image thumb.
+   * @param index Number that represents the index of the image that you clicked.
+   */
   onShowModalGallery(index: number) {
     this.showModalGallery(index);
   }
 
+  /**
+   * Method `showModalGallery` to show the modal gallery displaying the image with
+   * the index specified as input parameter.
+   * It will also register a new `keyboardService` to catch keyboard's events to download the current
+   * image with keyboard's shortcuts. This service, will be removed when modal-gallery component will be destroyed.
+   * @param index Number that represents the index of the image to show.
+   */
   showModalGallery(index: number) {
     this.keyboardService.add((event: KeyboardEvent, combo: string) => {
       if (event.preventDefault) {
@@ -305,6 +356,10 @@ export class AngularModalGallery implements OnInit, OnDestroy, OnChanges {
     this.show.emit(new ImageModalEvent(Action.LOAD, this.currentImageIndex + 1));
   }
 
+  /**
+   * Method `downloadImage` to download the current visible image, only if `downloadable` is true.
+   * For IE, this will navigate to the image insted of a direct download as in all modern browsers.
+   */
   downloadImage() {
     if (!this.downloadable) {
       return;
@@ -319,12 +374,24 @@ export class AngularModalGallery implements OnInit, OnDestroy, OnChanges {
     document.body.removeChild(link);
   }
 
+  /**
+   * Method `onClickOutside` to close modal gallery when both `enableCloseOutside` is true and user
+   *  clicked on the semi-transparent background around the image.
+   * @param event Boolean that is true if user clicked on the semi-trasparent background, false otherwise.
+   */
   onClickOutside(event: boolean) {
     if(event && this.enableCloseOutside) {
       this.closeGallery(Action.CLICK);
     }
   }
 
+  /**
+   * Private method `getNextIndex` to get the next index, based on the action and the current index.
+   * This is necessary because at the end and calling prnextev again, you'll go to the first image, because they are shown like in a circle.
+   * @param action Enum of type Action that represents the source of the event that changed the
+   *  current image to the next one.
+   * @param currentIndex Number that represents the current index of the visible image.
+   */
   private getNextIndex(action: Action, currentIndex: number): number {
     let newIndex: number = 0;
     if (currentIndex >= 0 && currentIndex < this.images.length - 1) {
@@ -342,6 +409,13 @@ export class AngularModalGallery implements OnInit, OnDestroy, OnChanges {
     return newIndex;
   }
 
+  /**
+   * Private method `getPrevIndex` to get the previous index, based on the action and the current index.
+   * This is necessary because at index 0 and calling prev again, you'll go to the last image, because they are shown like in a circle.
+   * @param action Enum of type Action that represents the source of the event that changed the
+   *  current image to the previous one.
+   * @param currentIndex Number that represents the current index of the visible image.
+   */
   private getPrevIndex(action: Action, currentIndex: number): number {
     let newIndex: number = 0;
     if (currentIndex > 0 && currentIndex <= this.images.length - 1) {
@@ -359,6 +433,13 @@ export class AngularModalGallery implements OnInit, OnDestroy, OnChanges {
     return newIndex;
   }
 
+  /**
+   * Private method `emitBoundaryEvent` to emit events when either the last or the first image are visible.
+   * @param action Enum of type Action that represents the source of the event that changed the
+   *  current image to the first one or the last one.
+   * @param indexToCheck Number of type Action that represents the source of the event that changed the
+   *  current image to either the first or the last one.
+   */
   private emitBoundaryEvent(action: Action, indexToCheck: number) {
     // to emit first/last event
     switch (indexToCheck) {
@@ -371,10 +452,19 @@ export class AngularModalGallery implements OnInit, OnDestroy, OnChanges {
     }
   }
 
+  /**
+   * Method `getFileName` to get the filename from an input path.
+   * This is used to get the image's name from its path.
+   * @param path String that represents the path of the image.
+   */
   private getFileName(path: string) {
     return path.replace(/^.*[\\\/]/, '');
   }
 
+  /**
+   * Method `ngOnDestroy` to cleanup resources. In fact, this will unsubscribe
+   * all subscriptions and it will reset keyboard's service.
+   */
   ngOnDestroy() {
     if (this.subscription) {
       this.subscription.unsubscribe();

src/components/upper-buttons.component.ts

@@ -23,7 +23,7 @@
  */
 
 import { Input, Output, EventEmitter, Component } from '@angular/core';
-import { Image, ButtonsConfig } from './modal-gallery';
+import { Image, ButtonsConfig } from './modal-gallery.component';
 
 @Component({
   selector: 'upperButtons',

src/directives/close-button.directive.ts

@@ -1,5 +1,5 @@
 import { Directive, ElementRef, Input, OnChanges, SimpleChanges } from '@angular/core';
-import { ButtonsConfig } from '../components/modal-gallery';
+import { ButtonsConfig } from '../components/modal-gallery.component';
 
 @Directive({
   selector: '[close-button]'

src/directives/download-button.directive.ts

@@ -1,5 +1,5 @@
 import { Directive, ElementRef, Input, OnChanges, SimpleChanges } from '@angular/core';
-import { ButtonsConfig } from '../components/modal-gallery';
+import { ButtonsConfig } from '../components/modal-gallery.component';
 
 @Directive({
   selector: '[download-button]'

src/directives/external-url.directive.ts

@@ -1,5 +1,5 @@
 import { Directive, ElementRef, Input, OnChanges, SimpleChanges } from '@angular/core';
-import { ButtonsConfig } from '../components/modal-gallery';
+import { ButtonsConfig } from '../components/modal-gallery.component';
 
 @Directive({
   selector: '[exturl-button]'

src/modal-gallery.module.ts

@@ -15,26 +15,26 @@
 
  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
- FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ FITNESS FOR A PARTICULAR PURPOSE AND NON INFRINGEMENT. IN NO EVENT SHALL THE
  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  SOFTWARE.
  */
 
-import {NgModule, ModuleWithProviders} from '@angular/core';
-import {CommonModule} from '@angular/common';
+import { NgModule, ModuleWithProviders } from '@angular/core';
+import { CommonModule } from '@angular/common';
 
-import {AngularModalGallery} from './components/modal-gallery';
-import {DIRECTIVES} from './directives/directives';
-import {UpperButtonsComponent} from './components/upper-buttons.component';
-import {KeyboardService} from './components/keyboard.service';
-import {Gallery} from './components/gallery.component';
+import { AngularModalGallery } from './components/modal-gallery.component';
+import { DIRECTIVES } from './directives/directives';
+import { UpperButtonsComponent } from './components/upper-buttons.component';
+import { KeyboardService } from './components/keyboard.service';
+import { Gallery } from './components/gallery.component';
 
 @NgModule({
-  imports: [CommonModule],
-  declarations: [AngularModalGallery, UpperButtonsComponent, Gallery, DIRECTIVES],
-  exports: [AngularModalGallery]
+  imports: [ CommonModule ],
+  declarations: [ AngularModalGallery, UpperButtonsComponent, Gallery, DIRECTIVES ],
+  exports: [ AngularModalGallery ]
 })
 export class AngularModalGalleryModule {
   static forRoot(): ModuleWithProviders {