From 275f39c28d05423a69a3c0a451b17fef45315aa4 Mon Sep 17 00:00:00 2001 From: Benny Powers Date: Sun, 24 Jan 2021 14:27:20 +0200 Subject: [PATCH] docs: use docblocks for types --- types-packages/busy-signal.d.ts | 70 +++++++++++++++++++--------- types-packages/datatip.d.ts | 23 ++++++--- types-packages/definitions.d.ts | 61 ++++++++++++++++-------- types-packages/find-references.d.ts | 25 +++++++--- types-packages/hyperclick.d.ts | 32 +++++++++---- types-packages/main.d.ts | 14 ++++-- types-packages/markdown-service.d.ts | 7 ++- types-packages/outline.d.ts | 28 ++++++++--- 8 files changed, 186 insertions(+), 74 deletions(-) diff --git a/types-packages/busy-signal.d.ts b/types-packages/busy-signal.d.ts index fcf3b457..0967ca08 100644 --- a/types-packages/busy-signal.d.ts +++ b/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(title: string, f: () => Promise, options?: BusySignalOptions): Promise - // 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 diff --git a/types-packages/datatip.d.ts b/types-packages/datatip.d.ts index 8a4cf4e5..0b538013 100644 --- a/types-packages/datatip.d.ts +++ b/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 - // 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 } @@ -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 } diff --git a/types-packages/definitions.d.ts b/types-packages/definitions.d.ts index 3ceea58e..30477701 100644 --- a/types-packages/definitions.d.ts +++ b/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 | null | undefined - definitions: ReadonlyArray // Must be non-empty. + /** + * Must be non-empty. + */ + definitions: ReadonlyArray } -// 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 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 } diff --git a/types-packages/find-references.d.ts b/types-packages/find-references.d.ts index 3a388c1b..05d9ae6c 100644 --- a/types-packages/find-references.d.ts +++ b/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 - // `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 } 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 { diff --git a/types-packages/hyperclick.d.ts b/types-packages/hyperclick.d.ts index a7010624..7df24fdb 100644 --- a/types-packages/hyperclick.d.ts +++ b/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 - // 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 }> } diff --git a/types-packages/main.d.ts b/types-packages/main.d.ts index 3f79e0ed..1651cfe1 100644 --- a/types-packages/main.d.ts +++ b/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 } diff --git a/types-packages/markdown-service.d.ts b/types-packages/markdown-service.d.ts index 2a10f825..f550c5ba 100644 --- a/types-packages/markdown-service.d.ts +++ b/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 } diff --git a/types-packages/outline.d.ts b/types-packages/outline.d.ts index 4e91dbe6..9ef7b1e6 100644 --- a/types-packages/outline.d.ts +++ b/types-packages/outline.d.ts @@ -2,8 +2,10 @@ import * as Atom from "atom" export interface OutlineProvider { name: string - // 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 updateOnEdit?: boolean @@ -11,14 +13,24 @@ export interface OutlineProvider { } export interface OutlineTree { - icon?: string // from Atom.Octicon (that type's not allowed over rpc so we use string) - kind?: OutlineTreeKind // kind you can pass to the UI for theming + /** + * from Atom.Octicon (that type's not allowed over rpc so we use string) + */ + icon?: string + /** + * kind you can pass to the UI for theming + */ + kind?: OutlineTreeKind - // Must be one or the other. If both are present, tokenizedText is preferred. + /** + * Must be one or the other. If both are present, tokenizedText is preferred. + */ plainText?: string tokenizedText?: TokenizedText - // If user has atom-ide-base-outline-view.nameOnly then representativeName is used instead. + /** + * If user has atom-ide-base-outline-view.nameOnly then representativeName is used instead. + */ representativeName?: string startPosition: Atom.Point @@ -31,7 +43,9 @@ export interface Outline { outlineTrees: OutlineTree[] } -// Kind of outline tree - matches the names from the Language Server Protocol v2. +/** + * Kind of outline tree - matches the names from the Language Server Protocol v2. + */ export type OutlineTreeKind = | "file" | "module"