feat: new layout of signature help

atom-community · Apr 18, 2019 · 2c93227 · 2c93227
1 parent baef926
commit 2c93227
Show file tree

Hide file tree

Showing 9 changed files with 267 additions and 138 deletions.
diff --git a/lib/main.js b/lib/main.js
@@ -1,8 +1,14 @@
+// @ts-check
+/// <reference path="../typings/atom-ide.d.ts"/>
 'use babel';
 
 const { CompositeDisposable } = require('atom');
 const SignatureHelpManager = require('./signature-help-manager');
 
+/**
+ * the Atom IDE signature help plugin
+ * @type {Object}
+ */
 module.exports = {
 
   /**
@@ -15,25 +21,21 @@ module.exports = {
    * @type {SignatureHelpManager}
    */
   signatureHelpManager: null,
-
   /**
-   * [renderer description]
-   * @type {[type]}
+   * a reference to the markdown rendering service
+   * @type {AtomIDE.MarkdownService}
    */
   renderer: null,
 
   /**
    * called by Atom when activating an extension
-   * @param  {[type]} state [description]
+   * @param  {any} state the current state of atom
    */
   activate(state) {
-
     // Events subscribed to in atom's system can be easily cleaned up with a CompositeDisposable
     this.subscriptions = new CompositeDisposable();
-
     if (!this.signatureHelpManager) this.signatureHelpManager = new SignatureHelpManager();
     this.subscriptions.add(this.signatureHelpManager);
-
     require('atom-package-deps').install('atom-ide-signature-help').then(() => {
       this.signatureHelpManager.initialize(this.renderer);
     });
@@ -47,18 +49,21 @@ module.exports = {
       this.subscriptions.dispose();
     }
     this.subscriptions = null;
+    this.signatureHelpManager = null;
   },
 
   /**
    * [provideDatatipService description]
    * @return {AtomIDE.SignatureHelpRegistry} [description]
    */
   provideSignatureHelp() {
-    return (provider) => {
-      return this.signatureHelpManager.addProvider(provider);
-    }
+    return this.signatureHelpManager.signatureHelpRegistry;
   },
 
+  /**
+   * retrieves a reference to the markdown rendering service that should be used
+   * @param  {AtomIDE.MarkdownService} renderer the service for rendering markdown text
+   */
   consumeMarkdownRenderer(renderer) {
     this.renderer = renderer;
   }

diff --git a/lib/provider-registry.js b/lib/provider-registry.js
@@ -4,18 +4,23 @@
 
 const { Disposable, TextEditor } = require('atom');
 
+/**
+ * the registry of signature help providers
+ */
 module.exports = class ProviderRegistry {
+
   constructor() {
     /**
-     * [providers description]
+     * the initial empty provider list
      * @type {Array<AtomIDE.SignatureHelpProvider>}
      */
     this.providers = [];
   }
 
   /**
-   * [addProvider description]
-   * @param {AtomIDE.SignatureHelpProvider} provider [description]
+   * adds a signature help provider to the registry
+   * @param {AtomIDE.SignatureHelpProvider} provider the data tip provider to be added
+   * @return {Disposable} a disposable object to clean up the provider registration later
    */
   addProvider(provider) {
     const index = this.providers.findIndex(
@@ -31,7 +36,7 @@ module.exports = class ProviderRegistry {
   }
 
   /**
-   * [removeProvider description]
+   * removes a signature help provider from the registry
    * @param  {AtomIDE.SignatureHelpProvider} provider [description]
    */
   removeProvider(provider) {
@@ -42,30 +47,29 @@ module.exports = class ProviderRegistry {
   }
 
   /**
-   * [getProviderForEditor description]
-   * @param  {TextEditor} editor [description]
-   * @return {AtomIDE.SignatureHelpProvider}        [description]
+   * looks for the first known provider to a given Atom text editor
+   * @param  {TextEditor} editor the Atom text editor to be looked for
+   * @return {AtomIDE.SignatureHelpProvider | null} a signature help provider if found
    */
   getProviderForEditor(editor) {
     const grammar = editor.getGrammar().scopeName;
     return this.findProvider(grammar);
   }
 
-  // TODO create an ordering or priority aware util to prefer instead.
   /**
-   * [getAllProvidersForEditor description]
-   * @param  {TextEditor} editor [description]
-   * @return {Iterable<AtomIDE.SignatureHelpProvider>}        [description]
+   * looks for all known providers of a given Atom text editor
+   * @param  {TextEditor} editor the Atom text editor to be looked for
+   * @return {Array<AtomIDE.SignatureHelpProvider>}  a list of signature help providers available for this editor
    */
   getAllProvidersForEditor(editor) {
     const grammar = editor.getGrammar().scopeName;
     return this.findAllProviders(grammar);
   }
 
   /**
-   * [findProvider description]
-   * @param  {string} grammar [description]
-   * @return {AtomIDE.SignatureHelpProvider | null}         [description]
+   * internal helper function to look for the first signature help provider for a specific grammar
+   * @param  {String} grammar the grammar scope to be looked for
+   * @return {AtomIDE.SignatureHelpProvider | null}   a signature help provider available for that grammar, or null if none
    */
   findProvider(grammar) {
     for (const provider of this.findAllProviders(grammar)) {
@@ -75,9 +79,9 @@ module.exports = class ProviderRegistry {
   }
 
   /**
-   * [findAllProviders description]
-   * @param  {string}    grammar [description]
-   * @return {IterableIterator<AtomIDE.SignatureHelpProvider>}         [description]
+   * internal helper to look for all signature help providers for a specific grammar
+   * @param  {String}    grammar the grammar scope to be looked for
+   * @return {Array<AtomIDE.SignatureHelpProvider>}   a list of all known signature help providers for that grammar
    */
   *findAllProviders(grammar) {
     for (const provider of this.providers) {