docs: use docblocks for types

types-packages/busy-signal.d.ts

@@ -1,50 +1,76 @@
 export interface BusySignalOptions {
-  // Can say that a busy signal will only appear when a given file is open.
-  // Default = `null`, meaning the busy signal applies to all files.
+  /**
+   * Can say that a busy signal will only appear when a given file is open.
+   * Default = `null`, meaning the busy signal applies to all files.
+   */
   onlyForFile?: string
-  // Is user waiting for computer to finish a task? (traditional busy spinner)
-  // or is the computer waiting for user to finish a task? (action required)
-  // Default = spinner.
+  /**
+   * Is user waiting for computer to finish a task? (traditional busy spinner)
+   * or is the computer waiting for user to finish a task? (action required)
+   * Default = spinner.
+   */
   waitingFor?: "computer" | "user"
-  // Debounce it? default = `true` for busy-signal, and false for action-required.
+  /**
+   * Debounce it? default = `true` for busy-signal, and false for action-required.
+   */
   debounce?: boolean
-  // If `onClick` is set, then the tooltip will be clickable. Default = `null`.
+  /**
+   * If `onClick` is set, then the tooltip will be clickable. Default = `null`.
+   */
   onDidClick?: () => void
-  // If set to `true`, the busy signal tooltip will be immediately revealed
-  // when it first becomes visible (without explicit mouse interaction).
+  /**
+   * If set to `true`, the busy signal tooltip will be immediately revealed
+   * when it first becomes visible (without explicit mouse interaction).
+   */
   revealTooltip?: boolean
 }
 
-// atom-ide-busy-signal service
+/**
+ * atom-ide-busy-signal service
+ */
 export interface BusySignalService {
-  // Activates the busy signal with the given title and returns the promise
-  // from the provided callback.
-  // The busy signal automatically deactivates when the returned promise
-  // either resolves or rejects.
+  /**
+   * Activates the busy signal with the given title and returns the promise
+   * from the provided callback.
+   * The busy signal automatically deactivates when the returned promise
+   * either resolves or rejects.
+   */
   reportBusyWhile<T>(title: string, f: () => Promise<T>, options?: BusySignalOptions): Promise<T>
 
-  // Activates the busy signal. Set the title in the returned BusySignal
-  // object (you can update the title multiple times) and dispose it when done.
+  /**
+   * Activates the busy signal. Set the title in the returned BusySignal
+   * object (you can update the title multiple times) and dispose it when done.
+   */
   reportBusy(title: string, options?: BusySignalOptions): BusyMessage
 
-  // This is a no-op. When someone consumes the busy service, they get back a
-  // reference to the single shared instance, so disposing of it would be wrong.
+  /**
+   * This is a no-op. When someone consumes the busy service, they get back a
+   * reference to the single shared instance, so disposing of it would be wrong.
+   */
   dispose(): void
 }
 
 export interface BusyMessage {
-  // You can set/update the title.
+  /**
+   * You can set/update the title.
+   */
   setTitle(title: string): void
-  // Dispose of the signal when done to make it go away.
+  /**
+   * Dispose of the signal when done to make it go away.
+   */
   dispose(): void
 }
 
-// busy-signal service
+/**
+ * busy-signal service
+ */
 export interface BusySignalRegistry {
   create(): BusySignalProvider
 }
 
-// busy-signal service
+/**
+ * busy-signal service
+ */
 export interface BusySignalProvider {
   add(message: string): void
   remove(message: string): void

types-packages/datatip.d.ts

@@ -7,9 +7,13 @@ export interface DatatipService {
 }
 
 export interface PinnedDatatipOptions {
-  // Defaults to 'end-of-line'.
+  /**
+   * Defaults to 'end-of-line'.
+   */
   position?: PinnedDatatipPosition
-  // Defaults to true.
+  /**
+   * Defaults to true.
+   */
   showRangeHighlight?: boolean
 }
 
@@ -18,8 +22,10 @@ export type PinnedDatatipPosition = "end-of-line" | "above-range"
 export interface DatatipProvider {
   priority: number
   grammarScopes?: ReadonlyArray<string>
-  // A unique name for the provider to be used for analytics.
-  // It is recommended that it be the name of the provider's package.
+  /**
+   * A unique name for the provider to be used for analytics.
+   * It is recommended that it be the name of the provider's package.
+   */
   providerName: string
   datatip(editor: Atom.TextEditor, bufferPosition: Atom.Point): Promise<Datatip | undefined | null>
 }
@@ -37,7 +43,9 @@ export interface ModifierDatatipProvider {
 
 export type AnyDatatipProvider = DatatipProvider | ModifierDatatipProvider
 
-// Borrowed from the LSP API.
+/**
+ * Borrowed from the LSP API.
+ */
 export interface MarkdownMarkedString {
   type: "markdown"
   value: string
@@ -58,7 +66,10 @@ export interface MarkedStringDatatip {
 }
 
 export interface ReactComponentDatatip {
-  component: () => JSX.Element // React component
+  /**
+   * React component
+   */
+  component: () => JSX.Element
   range: Atom.Range
   pinnable?: boolean
 }

types-packages/definitions.d.ts

@@ -1,41 +1,64 @@
 import * as Atom from "atom"
 
 export interface Definition {
-  // Path of the file in which the definition is located.
+  /**
+   * Path of the file in which the definition is located.
+   */
   path: string
-  // First character of the definition's identifier.
-  // e.g. "F" in `class Foo {}`
+  /**
+   * First character of the definition's identifier.
+   * e.g. "F" in `class Foo {}`
+   */
   position: Atom.Point
-  // Optional: the range of the entire definition.
-  // e.g. "c" to "}" in `class Foo {}`
+  /**
+   * Optional: the range of the entire definition.
+   * e.g. "c" to "}" in `class Foo {}`
+   */
   range?: Atom.Range
-  // Optional: `name` and `projectRoot` can be provided to display a more human-readable title
-  // inside of Hyperclick when there are multiple definitions.
+  /**
+   * Optional: `name` and `projectRoot` can be provided to display a more human-readable title
+   * inside of Hyperclick when there are multiple definitions.
+   */
   name?: string
-  // If provided, `projectRoot` will be used to display a relativized version of `path`.
+  /**
+   * If provided, `projectRoot` will be used to display a relativized version of `path`.
+   */
   projectRoot?: string
-  // `language` may be used by consumers to identify the source of definitions.
+  /**
+   * `language` may be used by consumers to identify the source of definitions.
+   */
   language: string
 }
 
-// Definition queries supply a point.
-// The returned queryRange is the range within which the returned definition is valid.
-// Typically queryRange spans the containing identifier around the query point.
-// (If a null queryRange is returned, the range of the word containing the point is used.)
+/**
+ * Definition queries supply a point.
+ * The returned queryRange is the range within which the returned definition is valid.
+ * Typically queryRange spans the containing identifier around the query point.
+ * (If a null queryRange is returned, the range of the word containing the point is used.)
+ */
 export interface DefinitionQueryResult {
   queryRange: ReadonlyArray<Atom.Range> | null | undefined
-  definitions: ReadonlyArray<Definition> // Must be non-empty.
+  /**
+   * Must be non-empty.
+   */
+  definitions: ReadonlyArray<Definition>
 }
 
-// Provides definitions for a set of language grammars.
+/**
+ * Provides definitions for a set of language grammars.
+ */
 export interface DefinitionProvider {
-  // If there are multiple providers for a given grammar,
-  // the one with the highest priority will be used.
+  /**
+   * If there are multiple providers for a given grammar,
+   * the one with the highest priority will be used.
+   */
   priority: number
   grammarScopes: ReadonlyArray<string>
   wordRegExp: RegExp | null | undefined
-  // Obtains the definition in an editor at the given point.
-  // This should return null if no definition is available.
+  /**
+   * Obtains the definition in an editor at the given point.
+   * This should return null if no definition is available.
+   */
   getDefinition: (editor: Atom.TextEditor, position: Atom.Point) => Promise<DefinitionQueryResult | null | undefined>
 }
 

types-packages/find-references.d.ts

@@ -1,17 +1,27 @@
 import * as Atom from "atom"
 
 export interface FindReferencesProvider {
-  // Return true if your provider supports finding references for the provided Atom.TextEditor.
+  /**
+   * Return true if your provider supports finding references for the provided Atom.TextEditor.
+   */
   isEditorSupported(editor: Atom.TextEditor): Promise<boolean>
 
-  // `findReferences` will only be called if `isEditorSupported` previously returned true
-  // for the given Atom.TextEditor.
+  /**
+   * `findReferences` will only be called if `isEditorSupported` previously returned true
+   * for the given Atom.TextEditor.
+   */
   findReferences(editor: Atom.TextEditor, position: Atom.Point): Promise<FindReferencesReturn | undefined | null>
 }
 
 export interface Reference {
-  uri: string // Nuclide URI of the file path
-  name: string | undefined | null // name of calling method/function/symbol
+  /**
+   * Nuclide URI of the file path
+   */
+  uri: string
+  /**
+   * name of calling method/function/symbol
+   */
+  name: string | undefined | null
   range: Atom.Range
 }
 
@@ -20,7 +30,10 @@ export interface FindReferencesData {
   baseUri: string
   referencedSymbolName: string
   references: Reference[]
-  title?: string // defaults to 'Symbol References'
+  /**
+   * defaults to 'Symbol References'
+   */
+  title?: string
 }
 
 export interface FindReferencesError {

types-packages/hyperclick.d.ts

@@ -1,8 +1,10 @@
 import * as Atom from "atom"
 
 export interface HyperclickProvider {
-  // Use this to provide a suggestion for single-word matches.
-  // Optionally set `wordRegExp` to adjust word-matching.
+  /**
+   * Use this to provide a suggestion for single-word matches.
+   * Optionally set `wordRegExp` to adjust word-matching.
+   */
   getSuggestionForWord?: (
     textEditor: Atom.TextEditor,
     text: string,
@@ -11,27 +13,39 @@ export interface HyperclickProvider {
 
   wordRegExp?: RegExp
 
-  // Use this to provide a suggestion if it can have non-contiguous ranges.
-  // A primary use-case for this is Objective-C methods.
+  /**
+   * Use this to provide a suggestion if it can have non-contiguous ranges.
+   * A primary use-case for this is Objective-C methods.
+   */
   getSuggestion?: (
     textEditor: Atom.TextEditor,
     position: Atom.Point
   ) => Promise<HyperclickSuggestion | null | undefined>
 
-  // Must be unique. Used for analytics.
+  /**
+   * Must be unique. Used for analytics.
+   */
   providerName?: string
 
-  // The higher this is, the more precedence the provider gets.
+  /**
+   * The higher this is, the more precedence the provider gets.
+   */
   priority: number
 
-  // Optionally, limit the set of grammar scopes the provider should apply to.
+  /**
+   * Optionally, limit the set of grammar scopes the provider should apply to.
+   */
   grammarScopes?: string[]
 }
 
 export interface HyperclickSuggestion {
-  // The range(s) to underline to provide as a visual cue for clicking.
+  /**
+   * The range(s) to underline to provide as a visual cue for clicking.
+   */
   range: Atom.Range | Atom.Range[]
 
-  // The function to call when the underlined text is clicked.
+  /**
+   * The function to call when the underlined text is clicked.
+   */
   callback: (() => void) | Array<{ rightLabel?: string; title: string; callback: () => void }>
 }

types-packages/main.d.ts

@@ -1,5 +1,7 @@
-// atom-ide
-// https://github.com/atom-ide-community/atom-ide-base
+/**
+ * @file atom-ide
+ * @see https://github.com/atom-ide-community/atom-ide-base
+ */
 
 export * from "./busy-signal"
 export * from "./code-actions"
@@ -23,9 +25,13 @@ import { OutlineProvider } from "./outline"
 import { SignatureHelpProvider } from "./sig-help"
 
 export interface ProviderCommon {
-  // Providers with higher priorities will be preferred over lower ones.
+  /**
+   * Providers with higher priorities will be preferred over lower ones.
+   */
   priority: number
-  // Omitting grammarScopes implies that the provider applies to all grammars.
+  /**
+   * Omitting grammarScopes implies that the provider applies to all grammars.
+   */
   grammarScopes?: Array<string>
 }
 

types-packages/markdown-service.d.ts

@@ -2,6 +2,11 @@
  * the markdown service object
  */
 export interface MarkdownService {
-  // function to render markdown for the given grammar
+  /**
+   * function to render markdown for the given grammar
+   * @param  markdownText markdown string to render
+   * @param  grammar      grammar to render the string with
+   * @return              highlighted HTML
+   */
   render(markdownText: string, grammar: string): Promise<string>
 }