Fill in more docs for app.ts and CodeEditor.ts, fix up some red squig…

…gles introduced by Idea's interpretation of jsdoc comments
hawtio · Nov 27, 2013 · 67461ce · 67461ce
1 parent b8246d3
commit 67461ce
Show file tree

Hide file tree

Showing 11 changed files with 130 additions and 32 deletions.
diff --git a/hawtio-api-docs/readme.md b/hawtio-api-docs/readme.md
@@ -61,6 +61,8 @@ Generally in hawtio a typescript module spans several files, so put the @main ta
 */
 ```
 
+If you don't care about types you can leave out the {foo} bit.  Note that Idea sees these as closure compiler types, so it'll interpret them, which can cause red squigglies, in which case just use {*} or leave out the type.
+
 For static functions that are in a module you could do:
 
 ```javascript

diff --git a/hawtio-web/src/main/webapp/app/api/js/apiHelpers.ts b/hawtio-web/src/main/webapp/app/api/js/apiHelpers.ts
@@ -79,7 +79,7 @@ module API {
    * @method loadJsonSchema
    * @for API
    * @static
-   * @param {any} jolokia
+   * @paran {*} jolokia
    * @param {String} mbean
    * @param {Function} onJsonSchemaFn
    */

diff --git a/hawtio-web/src/main/webapp/app/core/js/CodeEditor.ts b/hawtio-web/src/main/webapp/app/core/js/CodeEditor.ts
@@ -1,22 +1,75 @@
 /**
+ * Module that contains several helper functions related to hawtio's code editor
+ *
  * @module CodeEditor
  * @main CodeEditor
  */
 module CodeEditor {
   // TODO break this out into a separate plugin and maybe combine with hawtio-editor directive?
 
-  // TODO Wire up to a global config manager service
+  /**
+   * Options for the CodeMirror text editor
+   *
+   * @class CodeMirrorOptions
+   */
+  export interface CodeMirrorOptions {
+    /**
+     * @property theme
+     * @type String
+     */
+    theme: string;
+    /**
+     * @property tabSize
+     * @type number
+     */
+    tabSize: number;
+    /**
+     * @property lineNumbers
+     * @type boolean
+     */
+    lineNumbers: boolean;
+    /**
+     * @property indentWithTabs
+     * @type boolean
+     */
+    indentWithTabs: boolean;
+    /**
+     * @property lineWrapping
+     * @type boolean
+     */
+    lineWrapping: boolean;
+    /**
+     * @property autoClosetags
+     * @type boolean
+     */
+    autoClosetags: boolean;
+  }
+
+  /**
+   * @property GlobalCodeMirrorOptions
+   * @for CodeEditor
+   * @type CodeMirrorOptions
+   */
   export var GlobalCodeMirrorOptions = {
     theme: "default",
     tabSize: 4,
     lineNumbers: true,
     indentWithTabs: true,
     lineWrapping: true,
     autoCloseTags: true
-
-    // TODO Add autoformat option (Not explicitly a code mirror option)
   };
 
+  /**
+   * Controller used on the preferences page to configure the editor
+   *
+   * @method PreferencesController
+   * @for CodeEditor
+   * @static
+   * @param $scope
+   * @param workspace
+   * @param localStorage
+   * @param $templateCache
+   */
   export function PreferencesController($scope, workspace:Workspace, localStorage, $templateCache) {
     $scope.exampleText = $templateCache.get("exampleText");
     $scope.codeMirrorEx = $templateCache.get("codeMirrorExTemplate");
@@ -35,6 +88,16 @@ module CodeEditor {
 
   }
 
+  /**
+   * Tries to figure out what kind of text we're going to render in the editor, either
+   * text, javascript or XML.
+   *
+   * @method detectTextFormat
+   * @for CodeEditor
+   * @static
+   * @param value
+   * @returns {string}
+   */
   export function detectTextFormat(value: any):string {
     var answer = "text";
     if (value) {
@@ -52,6 +115,7 @@ module CodeEditor {
    *
    * @method autoFormatEditor
    * @for CodeEditor
+   * @static
    * @param {CodeMirrorEditor} editor
    * @return {void}
    */
@@ -71,6 +135,7 @@ module CodeEditor {
    *
    * @method createEditorSettings
    * @for CodeEditor
+   * @static
    * @param {Object} options
    * @return {Object}
    */

diff --git a/hawtio-web/src/main/webapp/app/core/js/app.ts b/hawtio-web/src/main/webapp/app/core/js/app.ts
@@ -3,6 +3,17 @@
  */
 module Core {
 
+  /**
+   * Controller that's attached to hawtio's drop-down console, mainly handles the
+   * clipboard icon at the bottom-right of the console.
+   *
+   * @method ConsoleController
+   * @for Core
+   * @static
+   * @param {*} $scope
+   * @param {*} $element
+   * @param {*} $templateCache
+   */
   export function ConsoleController($scope, $element, $templateCache) {
 
     $scope.setHandler = (clip) => {
@@ -31,6 +42,26 @@ module Core {
 
   }
 
+  /**
+   * Outermost controller attached to almost the root of the document, handles
+   * logging in and logging out, the PID/container indicator at the bottom right
+   * of the window and the document title
+   *
+   * @method AppController
+   * @for Core
+   * @static
+   * @param {*} $scope
+   * @param {ng.ILocationService} $location
+   * @param {Core.Workspace} workspace
+   * @param {*} jolokiaStatus
+   * @param {*} $document
+   * @param {Core.PageTitle} pageTitle
+   * @param {*} localStorage
+   * @param {*} userDetails
+   * @param {*} lastLocation
+   * @param {*} jolokiaUrl
+   * @param {*} branding
+   */
   export function AppController($scope, $location, workspace, jolokiaStatus, $document, pageTitle:Core.PageTitle, localStorage, userDetails, lastLocation, jolokiaUrl, branding) {
 
     if (userDetails.username === null) {

diff --git a/hawtio-web/src/main/webapp/app/core/js/coreHelpers.ts b/hawtio-web/src/main/webapp/app/core/js/coreHelpers.ts
@@ -100,7 +100,7 @@ function trimQuotes(text:string) {
  *
  * @method toSearchArgumentArray
  * @static
- * @param {Object} value
+ * @param {*} value
  * @return {String[]}
  *
  */
@@ -357,7 +357,7 @@ module Core {
    * @static
    * @method logout
    * @param {String} jolokiaUrl
-   * @param {Object} userDetails
+   * @param {*} userDetails
    * @param {Object} localStorage
    * @param {Object} $scope
    * @param {Function} successCB
@@ -432,7 +432,7 @@ module Core {
    * @method createHref
    * @for Core
    * @static
-   * @param {Object} $location
+   * @param {ng.ILocationService} $location
    * @param {String} href the link to have any $location.search() hash parameters appended
    * @param {Array} removeParams any parameters to be removed from the $location.search()
    * @return {Object} the link with any $location.search() parameters added
@@ -532,8 +532,8 @@ module Core {
    * @method register
    * @for Core
    * @static
-   * @param {Object} jolokia
-   * @param {Object} scope
+   * @param {*} jolokia
+   * @param {*} scope
    * @param {Object} arguments
    * @param {Function} callback
    */
@@ -571,8 +571,8 @@ module Core {
      * @method registerSearch
      * @for Core
      * @static
-     * @param {any} jolokia
-     * @param {ng.IScope} scope
+     * @paran {*} jolokia
+     * @param {*} scope
      * @param {String} mbeanPattern
      * @param {Function} callback
      */
@@ -658,7 +658,7 @@ module Core {
    * @method $applyNowOrLater
    * @for Core
    * @static
-   * @param {ng.IScope} $scope
+   * @param {*} $scope
    */
   export function $applyNowOrLater($scope) {
     if ($scope.$$phase || $scope.$root.$$phase) {
@@ -675,7 +675,7 @@ module Core {
    * @method $applyLater
    * @for Core
    * @static
-   * @param {ng.IScope} $scope
+   * @param {*} $scope
    * @param {Integer} timeout
    */
   export function $applyLater($scope, timeout = 50) {
@@ -690,7 +690,7 @@ module Core {
    * @method $apply
    * @for Core
    * @static
-   * @param {ng.IScope} $scope
+   * @param {*} $scope
    */
   export function $apply($scope) {
     var phase = $scope.$$phase || $scope.$root.$$phase;
@@ -1314,7 +1314,7 @@ module Core {
    * @method bindModelToSearchParam
    * @for Core
    * @static
-   * @param {ng.IScope} $scope
+   * @param {*} $scope
    * @param {ng.ILocationService} $location
    * @param {String} modelName
    * @param {String} paramName
@@ -1347,7 +1347,7 @@ module Core {
    * @for Core
    * @static
    * @param {Object} $route
-   * @param {ng.IScope} $scope
+   * @param {*} $scope
    * @param {ng.ILocationService} $location
    * @param {Array[String]} parameters
    */

diff --git a/hawtio-web/src/main/webapp/app/fabric/js/fabricHelpers.ts b/hawtio-web/src/main/webapp/app/fabric/js/fabricHelpers.ts
@@ -68,7 +68,7 @@ module Fabric {
    * @for Fabric
    * @param {any} $scope
    * @param {ng.ILocationService} $location
-   * @param {any} jolokia
+   * @paran {*} jolokia
    * @param {Workspace} workspace
    */
   export function initScope($scope, $location, jolokia, workspace) {
@@ -458,7 +458,7 @@ module Fabric {
    * into the onJolokia function
    * @method profileJolokia
    *
-   * @param {any} jolokia
+   * @paran {*} jolokia
    * @param {String} profileId
    * @param {String} versionId
    * @param {Function} onJolokia a function to receive the jolokia object or null if one cannot be created
@@ -475,7 +475,7 @@ module Fabric {
    * Attempts to create a jolokia for the given container id, passing the created object
    * into the onJolokia function
    * @method containerJolokia
-   * @param {any} jolokia
+   * @paran {*} jolokia
    * @param {String} containerId the id of the container to connect to
    * @param {Function} onJolokia a function to receive the jolokia object or null if one cannot be created
    */

diff --git a/hawtio-web/src/main/webapp/app/jclouds/js/provider.ts b/hawtio-web/src/main/webapp/app/jclouds/js/provider.ts
@@ -8,7 +8,7 @@ module Jclouds {
    *
    * @method ProviderController
    * @for Jclouds
-   * @param {ng.IScope} $scope
+   * @param {*} $scope
    * @param {ng.IFilterService} $filter
    * @param {Workspace} workspace
    * @param {ng.IRouteParamsService} $routeParams

diff --git a/hawtio-web/src/main/webapp/app/jvm/js/jvmHelpers.ts b/hawtio-web/src/main/webapp/app/jvm/js/jvmHelpers.ts
@@ -7,7 +7,7 @@ module JVM {
    * Adds common properties and functions to the scope
    * @method configureScope
    * @for Jvm
-   * @param {ng.IScope} $scope
+   * @param {*} $scope
    * @param {ng.ILocationService} $location
    * @param {Core.Workspace} workspace
    */

diff --git a/hawtio-web/src/main/webapp/app/perspective/js/defaultPage.ts b/hawtio-web/src/main/webapp/app/perspective/js/defaultPage.ts
@@ -7,7 +7,7 @@ module Perspective {
    * redirects the browser to the default page based on the detected profiles
    * @method DefaultPageController
    * @for Perspective
-   * @param {ng.IScope} $scope
+   * @param {*} $scope
    * @param {ng.ILocationService} $location
    * @param {any} localStorage
    * @param {Core.Workspace} workspace

diff --git a/hawtio-web/src/main/webapp/app/perspective/js/perspectiveHelpers.ts b/hawtio-web/src/main/webapp/app/perspective/js/perspectiveHelpers.ts
@@ -38,7 +38,7 @@ module Perspective {
    * @for Perspective
    * @param {ng.ILocationService} $location
    * @param {Core.Workspace} workspace
-   * @param {any} jolokia
+   * @paran {*} jolokia
    * @param {any} localStorage
    * @return {String}
    */
@@ -56,7 +56,7 @@ module Perspective {
    * @for Perspective
    * @param {ng.ILocationService} $location
    * @param {Core.Workspace} workspace
-   * @param {any} jolokia
+   * @paran {*} jolokia
    * @param {any} localStorage
    */
   export function getPerspectives($location, workspace, jolokia, localStorage) {
@@ -145,7 +145,7 @@ module Perspective {
    * @for Perspective
    * @param {ng.ILocationService} $location
    * @param {Core.Workspace} workspace
-   * @param {any} jolokia
+   * @paran {*} jolokia
    * @param {any} localStorage
    * @return {Array}
    */
@@ -161,7 +161,7 @@ module Perspective {
    * @for Perspective
    * @param {ng.ILocationService} $location
    * @param {Core.Workspace} workspace
-   * @param {any} jolokia
+   * @paran {*} jolokia
    * @param {any} localStorage
    * @return {String}
    */
@@ -186,7 +186,7 @@ module Perspective {
    * @for Perspective
    * @param {ng.ILocationService} $location
    * @param {Core.Workspace} workspace
-   * @param {any} jolokia
+   * @paran {*} jolokia
    * @param {any} localStorage
    * @return {String}
    */