Merge pull request #307 from presidential-innovation-fellows/chore/ad…

…d-documentation

Add JSDoc to many of the components.

src/app/components/policy-guide/policy-guide.component.ts

@@ -1,13 +1,23 @@
 import { Component } from '@angular/core';
 import { StateService } from '../../services/state';
 
+/**
+ * Class representing the policy guide.
+ */
+
 @Component({
   selector: 'policy-guide',
   styles: [require('./policy-guide.style.scss')],
   template: require('./policy-guide.template.html')
 })
 export class PolicyGuideComponent {
 
+  /**
+   * Constructs a PolicyGuideComponent.
+   *
+   * @constructor
+   * @param {StateService} stateService - A service for managing the state of the site
+   */
   constructor(public stateService: StateService) {
     this.stateService.set('section', 'policy-guide');
   }

src/app/components/privacy-policy/privacy-policy.component.ts

@@ -2,6 +2,10 @@ import { Component } from '@angular/core';
 import { StateService } from '../../services/state';
 import { SeoService } from '../../services/seo';
 
+/**
+ * Class representing a privacy policy.
+ */
+
 @Component({
   selector: 'privacy-policy',
   styles: [require('./privacy-policy.style.scss')],
@@ -10,6 +14,13 @@ import { SeoService } from '../../services/seo';
 
 export class PrivacyPolicyComponent {
 
+  /**
+   * Construct a PrivacyPolicyComponent.
+   *
+   * @constructor
+   * @param {SeoService} seoService - A service for setting SEO related tags
+   * @param {StateService} stateService - A service for managing the state of the site
+   */
   constructor(
     private seoService: SeoService,
     public stateService: StateService

src/app/components/repo-list-item/repo-list-item.component.ts

@@ -4,6 +4,10 @@ import { Subject }    from 'rxjs/Subject';
 import { RepoComponent } from '../repo';
 import { TruncatePipe } from '../../../pipes/truncate';
 
+/**
+ * Class representing a component for repositories in a list view.
+ */
+
 @Component({
   selector: 'repo-list-item',
   styles: [require('./repo-list-item.styles.scss')],
@@ -13,5 +17,10 @@ import { TruncatePipe } from '../../../pipes/truncate';
 export class RepoListItemComponent {
   @Input() repo;
 
+  /**
+   * Constructs a RepoListItemComponent.
+   *
+   * @constructor
+   */
   constructor() {}
 }

src/app/components/repo-list/repo-list.component.ts

@@ -3,6 +3,10 @@ import { Subscription } from 'rxjs';
 
 import { SearchService } from '../../services/search';
 
+/**
+ * Class representing a list of repositories.
+ */
+
 @Component({
   selector: 'repo-list',
   template: require('./repo-list.template.html'),
@@ -14,6 +18,12 @@ export class RepoListComponent {
   private subscription: Subscription;
   private total: number;
 
+  /**
+   * Constructs a RepoListComponent.
+   *
+   * @constructor
+   * @param {SearchService} searchService - A service for searching repositories
+   */
   constructor(
     private searchService: SearchService,
   ) {
@@ -23,14 +33,28 @@ export class RepoListComponent {
     });
   }
 
+  /**
+   * On removal from the DOM, unsubscribe from events.
+   */
   ngOnDestroy() {
     this.subscription.unsubscribe();
   }
 
+  /**
+   * When the list has some repositories.
+   *
+   * @return {void}
+   */
   hasRepos() {
     return this.results.length > 0;
   }
 
+  /**
+   * When the infinite scroll gets to its loading point, load the next
+   * page of results.
+   *
+   * @return {void}
+   */
   onScroll() {
     this.searchService.nextPage();
   }

src/app/components/repos-search/repos-search.component.ts

@@ -18,6 +18,10 @@ import { Router } from '@angular/router';
 import { SearchService } from '../../services/search';
 import { TermService } from '../../services/term';
 
+/**
+ * Class representing a search component for repositories.
+ */
+
 @Component({
   selector: 'repos-search',
   template: require('./repos-search.template.html'),
@@ -34,17 +38,34 @@ export class ReposSearchComponent {
   public autocompleteVisible: boolean = false;
   public queryInputValue: string = '';
 
+  /**
+   * Constructs a ReposSearchComponent.
+   *
+   * @constructor
+   * @param {FormBuilder} formBuilder - A service for building forms in angular
+   * @param {SearchService} searchService - A service for searching repositories
+   * @param {TermService} termService - A service for finding matching terms
+   * @param {Router} router - The application's URL router
+   */
   constructor(
     public formBuilder: FormBuilder,
     private searchService: SearchService,
     private termService: TermService,
     private router: Router,
   ) {}
 
+  /**
+   * Whether the user has entered any search terms.
+   *
+   * @return {boolean} true if the search input has values
+   */
   hasQuery(): boolean {
     return this.queryInputValue.length > 0;
   }
 
+  /**
+   * On initialization of the ReposSearchComponent
+   */
   ngOnInit() {
     this.searchForm = this.formBuilder.group({
       query: [''],
@@ -54,12 +75,21 @@ export class ReposSearchComponent {
     this.queryInputValue = this.queryValue;
   }
 
+  /**
+   * After everything has been added to the DOM
+   */
   ngAfterViewInit() {
     if (this.autofocus) {
       this.queryElement.nativeElement.focus();
     }
   }
 
+  /**
+   * Execute a search on every keypress. Escape and Enter blur the input.
+   *
+   * @param {Event} event - Keyboard event from user pressing a key
+   * @return {void}
+   */
   onKey(event: any) {
     this.queryInputValue = event.target.value;
     this.termService.search(this.queryInputValue);
@@ -69,26 +99,50 @@ export class ReposSearchComponent {
     }
   }
 
+  /**
+   * When form is submitted, go to search results page.
+   *
+   * @param {any} form - The form being submitted
+   * @return {void}
+   */
   onSubmit(form: any): void {
     this.search(form.query);
   }
 
+  /**
+   * Navigate to the search results page.
+   *
+   * @param {string} query - The search terms we are searching
+   * @return {void}
+   */
   search(query: string) {
     this.router.navigateByUrl('/search?q=' + query);
   }
 
+  /**
+   * Show the autocomplete dropdown.
+   */
   showAutocomplete() {
     this.autocompleteVisible = true;
   }
 
+  /**
+   * Hide the autocomplete dropdown.
+   */
   hideAutocomplete() {
     this.autocompleteVisible = false;
   }
 
-  onBlurHandler(e) {
-
+  /**
+   * When a click happens on the page, if it is outside the form,
+   * hide the autocomplete.
+   *
+   * @param {Event} event - The mouse click event.
+   * @return {void}
+   */
+  onBlurHandler(event: any) {
     const inputDoesNotHaveFocus = window.document.activeElement !== this.queryElement.nativeElement;
-    const clickIsOutsideForm = !this.searchFormElement.nativeElement.contains(e.target);
+    const clickIsOutsideForm = !this.searchFormElement.nativeElement.contains(event.target);
 
     if (inputDoesNotHaveFocus && clickIsOutsideForm) {
 

src/app/components/search-results/search-results.component.ts

@@ -8,6 +8,10 @@ import 'rxjs/add/operator/map';
 import { SearchService } from '../../services/search';
 import { StateService } from '../../services/state';
 
+/**
+ * Class representing a search results page for repositories.
+ */
+
 @Component({
   selector: 'search-results',
   styles: [require('./search-results.styles.scss')],
@@ -19,6 +23,14 @@ export class SearchResultsComponent {
   private queryValue: string = '';
   private subscription: Subscription;
 
+  /**
+   * Constructs a SearchResultsComponent.
+   *
+   * @constructor
+   * @param {StateService} stateService - A service for managing the state of the site
+   * @param {ActivatedRoute} activatedRoute - The currently active route
+   * @param {SearchService} searchService - A service for searching repositories
+   */
   constructor(
     public stateService: StateService,
     private activatedRoute: ActivatedRoute,
@@ -34,6 +46,9 @@ export class SearchResultsComponent {
     );
   }
 
+  /**
+   * On removal from the DOM, unsubscribe from URL updates.
+   */
   ngOnDestroy() {
     this.subscription.unsubscribe();
   }

src/app/components/sidebar/sidebar.component.ts

@@ -11,6 +11,10 @@ import { Subscription } from 'rxjs/Subscription';
 
 import { MobileService } from '../../services/mobile';
 
+/**
+ * Class representing a sidebar.
+ */
+
 @Component({
   selector: 'sidebar',
   styles: [require('./sidebar.style.scss')],
@@ -24,6 +28,13 @@ export class SidebarComponent implements OnDestroy, AfterViewInit {
   showTitle: boolean;
   @ViewChild('sidebarTitle') sidebarTitle: ElementRef;
 
+  /**
+   * Constructs a SidebarComponent.
+   *
+   * @constructor
+   * @param {MobileService} mobileService - service that detects whether the user is on a mobile device
+   * @param {ChangeDetectorRef} changeDetector - service for alerting Angular to update
+   */
   constructor(
     private mobileService: MobileService,
     private changeDetector: ChangeDetectorRef
@@ -38,11 +49,18 @@ export class SidebarComponent implements OnDestroy, AfterViewInit {
     );
   }
 
+  /**
+   * After the view is added to the DOM, show the sidebar title only if it has
+   * children elements.
+   */
   ngAfterViewInit() {
     this.showTitle = this.sidebarTitle.nativeElement.children.length > 0;
     this.changeDetector.detectChanges();
   }
 
+  /**
+   * On removal from DOM, remove listener for mobile sizing.
+   */
   ngOnDestroy() {
     if (this.activeMenuSub) this.activeMenuSub.unsubscribe();
   }

src/app/components/subnav/subnav.component.ts

@@ -1,5 +1,9 @@
 import { Component, ViewEncapsulation } from '@angular/core';
 
+/**
+ * Class representing a subnav.
+ */
+
 @Component({
   selector: 'subnav',
   styles: [require('./subnav.style.scss')],

src/app/components/tools/schema-validator/schema-validator.component.ts

@@ -2,6 +2,10 @@ import { Component, ChangeDetectorRef } from '@angular/core';
 import { MonacoEditorService } from '../../monaco-editor';
 const _ = require('lodash');
 
+/**
+ * Class representing the schema validator tool.
+ */
+
 @Component({
   selector: 'schema-validator',
   template: require('./schema-validator.template.html'),
@@ -16,6 +20,13 @@ export class SchemaValidatorComponent {
   private errors = [];
   private version = '2.0.0';
 
+  /**
+   * Constructs a SchemaValidatorComponent.
+   *
+   * @constructor
+   * @param {MonacoEditorService} monacoEditor - a service keeping track of the Monaco editor state
+   * @param {ChangeDetectorRef} changeDetectorRef - service for alerting Angular to update
+   */
   constructor(
     private monacoEditor: MonacoEditorService,
     private changeDetectorRef: ChangeDetectorRef,
@@ -24,6 +35,11 @@ export class SchemaValidatorComponent {
     monacoEditor.addSchema('1.0.1.json', ['*-1.0.1.json'], require('../../../../assets/schemas/1.0.1.json'));
   }
 
+  /**
+   * When setting the model, update the errors list.
+   *
+   * @param {any} m - the new Model for the Monaco Editor
+   */
   set model(m) {
     this._model = m;
     this._model.onDidChangeDecorations(() => {
@@ -33,10 +49,18 @@ export class SchemaValidatorComponent {
     });
   }
 
+  /**
+   * Get the current Model for the Monaco Editor.
+   */
   get model() {
     return this._model;
   }
 
+  /**
+   * Scroll the Monaco Editor to the position of an error.
+   *
+   * @param {any} error - a Monaco Marker representing an error in the user's input
+   */
   scrollToError(error) {
     const { startMarker, endMarker } = error;
     const range = new this.monaco.Range(