add more documentation and comments

src/plugin/config.ts

 namespace Config {
     export const nodeSize: number = 30;
-    export const interactionClickEvent: string = 'PDB.interactions.click';
-    export const interactionMouseoverEvent: string = 'PDB.interactions.mouseover';
-    export const interactionMouseoutEvent: string = 'PDB.interactions.mouseout'
+    export const interactionClickEvent: string = "PDB.interactions.click";
+    export const interactionMouseoverEvent: string = "PDB.interactions.mouseover";
+    export const interactionMouseoutEvent: string = "PDB.interactions.mouseout"
 
-    export const interactionShowLabelEvent: string = 'PDB.interactions.showLabel';
-    export const interactionHideLabelEvent: string = 'PDB.interactions.hideLabel';
+    export const interactionShowLabelEvent: string = "PDB.interactions.showLabel";
+    export const interactionHideLabelEvent: string = "PDB.interactions.hideLabel";
 
-    export const molstarClickEvent: string = 'PDB.molstar.click';
-    export const molstarMouseoverEvent: string = 'PDB.molstar.mouseover';
-    export const molstarMouseoutEvent: string = 'PDB.molstar.mouseout';
+    export const molstarClickEvent: string = "PDB.molstar.click";
+    export const molstarMouseoverEvent: string = "PDB.molstar.mouseover";
+    export const molstarMouseoutEvent: string = "PDB.molstar.mouseout";
 
     export const aaTypes = new Map<string, Array<string>>([
-        ['hydrophobic', new Array<string>('A', 'I', 'L', 'M', 'F', 'W', 'V')],
-        ['positive', Array<string>('K', 'R', 'O')],
-        ['negative', Array<string>('E', 'D')],
-        ['polar', Array<string>('N', 'Q', 'S', 'T')],
-        ['cystein', Array<string>('C', 'U')],
-        ['glycine', Array<string>('G')],
-        ['proline', Array<string>('P')],
-        ['aromatic', Array<string>('H', 'Y')]
+        ["hydrophobic", new Array<string>("A", "I", "L", "M", "F", "W", "V")],
+        ["positive", Array<string>("K", "R", "O")],
+        ["negative", Array<string>("E", "D")],
+        ["polar", Array<string>("N", "Q", "S", "T")],
+        ["cystein", Array<string>("C", "U")],
+        ["glycine", Array<string>("G")],
+        ["proline", Array<string>("P")],
+        ["aromatic", Array<string>("H", "Y")]
     ]);
 
     export const aaAbreviations = new Map<string, string>([
-        ['ALA', 'A'],
-        ['ARG', 'R'],
-        ['ASN', 'N'],
-        ['ASP', 'D'],
-        ['CYS', 'C'],
-        ['GLU', 'E'],
-        ['GLN', 'Q'],
-        ['GLY', 'G'],
-        ['HIS', 'H'],
-        ['ILE', 'I'],
-        ['LEU', 'L'],
-        ['LYS', 'K'],
-        ['MET', 'M'],
-        ['PHE', 'F'],
-        ['PRO', 'P'],
-        ['SER', 'S'],
-        ['THR', 'T'],
-        ['TRP', 'W'],
-        ['TYR', 'Y'],
-        ['VAL', 'V']
+        ["ALA", "A"],
+        ["ARG", "R"],
+        ["ASN", "N"],
+        ["ASP", "D"],
+        ["CYS", "C"],
+        ["GLU", "E"],
+        ["GLN", "Q"],
+        ["GLY", "G"],
+        ["HIS", "H"],
+        ["ILE", "I"],
+        ["LEU", "L"],
+        ["LYS", "K"],
+        ["MET", "M"],
+        ["PHE", "F"],
+        ["PRO", "P"],
+        ["SER", "S"],
+        ["THR", "T"],
+        ["TRP", "W"],
+        ["TYR", "Y"],
+        ["VAL", "V"]
     ]);
 
-    export const backboneAtoms: Array<string> = ['N', 'CA', 'C', 'O'];
+    export const backboneAtoms: Array<string> = ["N", "CA", "C", "O"];
 
+    // Mapping of interaction classes and interactions comming from arpeggio
     export const interactionsClasses = new Map<string, Array<string>>([
         ["covalent", new Array<string>("covalent")],
         ["electrostatic", new Array<string>("ionic", "hbond", "weak_hbond", "polar", "weak_polar", "xbond", "carbonyl")],
-        ['amide', new Array<string>("AMIDEAMIDE", "AMIDERING")],
+        ["amide", new Array<string>("AMIDEAMIDE", "AMIDERING")],
         ["vdw", new Array<string>("vdw")],
         ["hydrophobic", new Array<string>("hydrophobic")],
         ["aromatic", new Array<string>("aromatic", "FF", "OF", "EE", "FT", "OT", "ET", "FE", "OE", "EF")],
@@ -59,6 +60,13 @@ namespace Config {
         ["clashes", new Array<string>("clash", "vdw_clash")]
     ]);
 
+    /**
+     * Configuration of the UI menu (e.g. the hamburger visible in top
+     * right component's corner)
+     *
+     * @export
+     * @class UIParameters
+     */
     export class UIParameters {
         reinitialize: boolean;
         zoom: boolean;

src/plugin/depiction.ts

@@ -58,7 +58,7 @@ class Depiction {
 
 
     /**
-     * Returns an initial position of Residue node bound to a list of
+     * Returns an initial position of a Residue node bound to a list of
      * atom.
      *
      * Present implementation sorts all the partners based on the atom
@@ -74,12 +74,15 @@ class Depiction {
         if (this.atoms.length === 1) {
             return new Vector2D(this.atoms[0].position.x, this.atoms[0].position.y);
         }
-        // ideally we want to find an atom which is part just a single bond to get nice initial position.
-        // If there is no such atom any will do
+        // ideally we want to find an atom which is part of just
+        // a single bond to get nice initial position.
+        // If there is no such atom any would do.
 
-        let atoms = this.atoms.filter(x => atomNames.includes(x.name)).sort((x, y) => x.connectivity - y.connectivity);
-        let thisAtom = atoms[0];
+        let atoms = this.atoms
+            .filter(x => atomNames.includes(x.name))
+            .sort((x, y) => x.connectivity - y.connectivity);
 
+        let thisAtom = atoms[0];
         let bond = this.bonds.find(x => x.containsAtom(thisAtom));
         let otherAtom = bond.getOtherAtom(thisAtom);
 
@@ -90,6 +93,13 @@ class Depiction {
         return new Vector2D(x, y);
     }
 
+    /**
+     * Draw ligand depiction to the canvas using D3.js. Any previous
+     * ligands are discarded.
+     *
+     * @param {boolean} [atomNames=false] Whether or not atom names should be drawn.
+     * @memberof Depiction
+     */
     public draw(atomNames: boolean = false) {
         this.structure.selectAll("*").remove();
 
@@ -99,6 +109,15 @@ class Depiction {
         else this.appendLabels();
     }
 
+    /**
+     * Highlight substructure of a depiction formed by a list of atoms.
+     * Any former highlights are discarded.
+     *
+     * @param {Array<string>} atoms List of atoms to be displayed
+     * @param {string} [color=undefined] highlight collor
+     * @returns
+     * @memberof Depiction
+     */
     public highlightSubgraph(atoms: Array<string>, color: string = undefined) {
         if (!this.atoms || !atoms) return;
 
@@ -126,6 +145,15 @@ class Depiction {
             .attr('style', `fill:none;fill-rule:evenodd;stroke:${color};stroke-width:22px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1`)
     }
 
+    /**
+     * Add code so that the component can draw contour levels. Shape of
+     * data is driven by the requirements of the D3.js code.
+     *
+     * TODO
+     *
+     * @param {*} data to be decided
+     * @memberof Depiction
+     */
     public addContour(data: any) {
         this.contour.selectAll('*').remove();
 

src/plugin/manager.ts

@@ -537,6 +537,12 @@ class Visualization {
         return 'blank.svg';
     }
 
+    /**
+     * Remove fixed positions of nodes, after they have been manipulated with.
+     *
+     * @private
+     * @memberof Visualization
+     */
     private nullNodesPositions() {
         this.presentBindingSite.interactionNodes.forEach((x: Model.InteractionNode) => {
             if (!x.static) {
@@ -547,7 +553,7 @@ class Visualization {
 
     }
 
-    // #region fire events
+    // #region fire events For component interoperability with other components
 
     private fireExternalLinkEvent(link: Model.Link, eventName: string) {
         let atomsSource = [];
@@ -643,6 +649,15 @@ class Visualization {
 
 
 
+    /**
+     * Add labels to the InteractionNodes e.g.
+     *
+     * ALA
+     * 42
+     * @private
+     * @param {*} selection
+     * @memberof Visualization
+     */
     private addNodeLabels(selection: any) {
         selection
             .append('text')
@@ -662,7 +677,8 @@ class Visualization {
     //#endregion
 
     /**
-     * Initialize scene after user selected a part of bound molecule.
+     * Initialize scene after user selected a a ligand that is a part of
+     * bound molecule.
      *
      * @private
      * @param {Model.InteractionNode} n Interaction node user clicked to
@@ -707,10 +723,14 @@ class Visualization {
 
 
     /**
-     * Setup ligand scene for display of ligand and interactions.
-     * This includes: setup of links, nodes, simulation and subscribing to relevant events.
+     * Setup display of interactions for a ligand
+     * This includes:
+     *    setup of links
+     *    nodes
+     *    simulation
+     *    subscribing to relevant events.
      *
-     * Depiction is expected to be downloaded already.
+     * Depiction is expected to be downloaded already!
      *
      * @private
      * @memberof Visualization
@@ -783,7 +803,12 @@ class Visualization {
 
     /**
      * Setup display of interactions for bound molecule.
-     * * This includes: setup of links, nodes, simulation and subscribing to relevant events.
+     * This includes:
+     *    setup of links
+     *    nodes
+     *    simulation
+     *    subscribing to relevant events.
+     *
      * No depiction is required for this step.
      *
      * @private
@@ -881,6 +906,15 @@ class Visualization {
     }
 
 
+    /**
+     * Dim all the nodes but the selected one.
+     *
+     * @private
+     * @param {Model.InteractionNode} x
+     * @param {number} i
+     * @param {*} g
+     * @memberof Visualization
+     */
     private nodeDim(x: Model.InteractionNode, i: number, g: any) {
         if (!x.static) x.scale = 1.0;
 
@@ -906,6 +940,15 @@ class Visualization {
             .attr('opacity', 0.4);
     }
 
+    /**
+     * Dim all the links but the selected one.
+     *
+     * @private
+     * @param {Model.Link} x
+     * @param {number} i
+     * @param {*} g
+     * @memberof Visualization
+     */
     private linkDim(x: Model.Link, i: number, g: any) {
         let parent = d3.select(g[i]).node().parentNode;
         d3.select(parent).classed('pdb-lig-env-svg-bond-highlighted', false);

src/plugin/model.ts

@@ -28,6 +28,13 @@ namespace Model {
         Internal
     }
 
+    /**
+     * Utility to translate arpeggio interaction to component's
+     * interactions
+     *
+     * @export
+     * @class InteractionTypeUtil
+     */
     export class InteractionTypeUtil {
         public static parse(value: string) {
             if (value === 'atom_atom') return InteractionType.AtomAtom;
@@ -112,6 +119,17 @@ namespace Model {
         }
     }
 
+    /**
+     * Interaction node in the simulation. This is the colorful node
+     * that is being shown on the canvas and a transparent node per one
+     * heavy atom in ligand (for proper layout of the binding site).
+     *
+     * Implements D3 interface.
+     *
+     * @export
+     * @class InteractionNode
+     * @implements {d3.SimulationNodeDatum}
+     */
     export class InteractionNode implements d3.SimulationNodeDatum {
         id: string;
         residue: Residue;
@@ -154,12 +172,12 @@ namespace Model {
             let chainStr = splitted[0];
             let symString = "";
 
-            if (splitted.length > 1) { 
+            if (splitted.length > 1) {
                 symString = splitted[1] !== "1"? `[${splitted[1]}]` : "";
             }
-          
+
             let str = `${r.chemCompId} | ${chainStr}${symString} | ${r.authorResidueNumber}${r.authorInsertionCode}`;
-            
+
             return str;
         }
 
@@ -168,6 +186,15 @@ namespace Model {
         }
     }
 
+    /**
+     * Visual representation of the interaction between two residues or
+     * a residue and an atom. Percise color/type of the interaction is
+     * subsequently controlled by the pdb-ligand-env-svg.css file.
+     *
+     * @export
+     * @abstract
+     * @class Link
+     */
     export abstract class Link {
         public source: InteractionNode;
         public target: InteractionNode;
@@ -195,7 +222,7 @@ namespace Model {
             return (this.target.residue.equals(n) || this.source.residue.equals(n));
         }
 
-        public getOtherNode(node: InteractionNode) { 
+        public getOtherNode(node: InteractionNode) {
             return this.source.equals(node) ? this.target : this.source;
         }
 
@@ -204,6 +231,15 @@ namespace Model {
         abstract toTooltip(): string;
     }
 
+
+    /**
+     * Implementation of the Link for the BoundMolecule view
+     * e.g. bm1 of 3d12
+     *
+     * @export
+     * @class ResidueResidueLink
+     * @extends {Link}
+     */
     export class ResidueResidueLink extends Link {
         target: InteractionNode;
         source: InteractionNode
@@ -263,6 +299,13 @@ namespace Model {
     }
 
 
+    /**
+     * Implementation of the link for the Ligand view e.g REA of 1cbs
+     *
+     * @export
+     * @class LigandResidueLink
+     * @extends {Link}
+     */
     export class LigandResidueLink extends Link {
         interaction: Array<Interaction>;
 
@@ -335,10 +378,12 @@ namespace Model {
 
     }
 
-
     /**
      * DataObject representing the entire binding site with the bound
      * molecule and all its interactions.
+     *
+     * @export
+     * @class BindingSite
      */
     export class BindingSite {
         pdbId: string;
@@ -358,11 +403,19 @@ namespace Model {
         }
 
 
+        /**
+         * Initialize BindingSite from BoundMolecule API call
+         *
+         * @param {string} pdbId
+         * @param {*} data
+         * @returns {BindingSite}
+         * @memberof BindingSite
+         */
         public fromBoundMolecule(pdbId: string, data: any): BindingSite {
             this.pdbId = pdbId;
             this.bmId = data.bm_id;
 
-            this.tmpResidueSet = new ObjectSet<Residue>();
+            this.tmpResidueSet = new ObjectSet<Residue>(); // custom objects need to be unique
             this.tmpNodesSet = new ObjectSet<InteractionNode>();
 
             data.composition.ligands.forEach(x => this.tmpResidueSet.tryAdd(new Residue(x, true)));
@@ -394,6 +447,15 @@ namespace Model {
         }
 
 
+        /**
+         * Process API response interaction partner (BoundMolecule view).
+         * Create a new instance if not observed alread.
+         *
+         * @private
+         * @param {*} r
+         * @returns {InteractionNode} Interaction node to that partner
+         * @memberof BindingSite
+         */
         private processResidueInteractionPartner(r: any): InteractionNode {
             let residue = new Residue(r, false);
             residue = this.tmpResidueSet.tryAdd(residue);
@@ -404,6 +466,17 @@ namespace Model {
         }
 
 
+        /**
+         * Process API response interaction partner (Ligand view).
+         *
+         *
+         * @private
+         * @param {Residue} r
+         * @param {Depiction} d
+         * @param {string[]} atom_names
+         * @returns {InteractionNode} Interaction node to that partner
+         * @memberof BindingSite
+         */
         private processLigandInteractionPartner(r: Residue, d: Depiction, atom_names: string[]): InteractionNode {
             let scale = 0.0;
             if (r.isLigand) scale = atom_names.length > 1 ? 0.5 : 0.0
@@ -438,7 +511,7 @@ namespace Model {
 
                 if (bgnNode.residue.equals(endNode.residue)) {
                     this.tmpNodesSet.delete(endNode);
-                    return; // we do not want to show 'self interactions'  
+                    return; // we do not want to show 'self interactions'
                 }
 
                 let tmpLink = tmpLinks.find(x => x.containsBothNodes(bgnNode, endNode));
@@ -460,7 +533,7 @@ namespace Model {
         /**
          * Filter out Aromatic atom atom interactions provided there is
          * an evidence of the same atom being part of the stacking information
-         * 
+         *
          * This is for clarity purposes only.
          *
          * @private
@@ -495,5 +568,4 @@ namespace Model {
             return result;
         }
     }
-
 }
\ No newline at end of file

src/plugin/residuefactory.ts

 /**
  * Singleton instance to provide residue abbreviations to the component
+ * The idea behind is to treat modified AA like their parent molecules.
  *
  * @class ResidueProvider
  */

src/plugin/resources.ts

@@ -10,6 +10,14 @@ namespace Resources {
     export const componentLibraryURL: string = 'pdb-component-library/data/ligand-env';
     export const staticFilesURL: string = 'static/files/pdbechem_v2';
 
+    /**
+     * Retrieve file with mapping between glycan classes and SVG
+     * depictions
+     *
+     * @export
+     * @param {Model.Environment} env
+     * @returns URL with the file
+     */
     export function glycanSymbolsAPI(env: Model.Environment) {
         let url = '';
         switch (env) {
@@ -28,6 +36,13 @@ namespace Resources {
     }
 
 
+    /**
+     * Retrieve file with glycal classes and het code mappings
+     *
+     * @export
+     * @param {Model.Environment} env
+     * @returns URL with the file
+     */
     export function hetMappingAPI(env: Model.Environment) {
         let url = '';
         switch (env) {
@@ -46,6 +61,13 @@ namespace Resources {
     }
 
 
+    /**
+     * Path to the CSS file with SVG information
+     *
+     * @export
+     * @param {Model.Environment} env
+     * @returns URL of the file
+     */
     export function ligEnvCSSAPI(env: Model.Environment) {
         let url = '';
         switch (env) {
@@ -64,6 +86,14 @@ namespace Resources {
     }
 
 
+    /**
+     * Retrieve API URL with ligand annotation file (depiction)
+     *
+     * @export
+     * @param {string} ligandName
+     * @param {Model.Environment} env
+     * @returns {string}
+     */
     export function ligandAnnotationAPI(ligandName: string, env: Model.Environment): string {
         let url = '';
         switch (env) {
@@ -80,6 +110,15 @@ namespace Resources {
     }
 
 
+    /**
+     * Retrieve API URL for bound molecule interactions
+     *
+     * @export
+     * @param {string} pdbId
+     * @param {string} bmId
+     * @param {Model.Environment} env
+     * @returns {string}
+     */
     export function boundMoleculeAPI(pdbId: string, bmId: string, env: Model.Environment): string {
         let url = '';
         switch (env) {
@@ -100,6 +139,16 @@ namespace Resources {
     }
 
 
+    /**
+     * Retrieve API URL for carbohydrate polymer.
+     *
+     * @export
+     * @param {string} pdbId
+     * @param {string} bmId
+     * @param {string} entityId
+     * @param {Model.Environment} env
+     * @returns {string}
+     */
     export function carbohydratePolymerAPI(pdbId: string, bmId: string, entityId: string, env: Model.Environment): string {
         let url = '';
         switch (env) {

src/plugin/ui.ts

@@ -116,6 +116,13 @@ let helpBonds = `
 
 
 
+/**
+ * Class manipulating the display of HTML elements on the top of the
+ * binding site view. Such as a tooltip, menu, extension functions of the
+ * menu etc. This is triggered by the events defined in config.ts file.
+ *
+ * @class UI
+ */
 class UI {
     private parent: HTMLElement;
     private display: Visualization;
@@ -308,6 +315,12 @@ class UI {
         }
     }
 
+    /**
+     * Show names of the ligand atom's.
+     *
+     * @private
+     * @memberof UI
+     */
     private showNames() {
         let btn = d3.select(this.parent).select('#pdb-lig-env-names-btn');
         let isActive = btn.classed('active');
@@ -355,7 +368,7 @@ class UI {
     }
 
     /**
-     * Switch component view and full screen.
+     * Switch component view to full screen and back.
      *
      * @private
      * @memberof UI