diff --git a/platform/lang-api/src/com/intellij/codeInsight/hints/InlayHintsProvider.kt b/platform/lang-api/src/com/intellij/codeInsight/hints/InlayHintsProvider.kt index 3f8a63356f8f..854d79052920 100644 --- a/platform/lang-api/src/com/intellij/codeInsight/hints/InlayHintsProvider.kt +++ b/platform/lang-api/src/com/intellij/codeInsight/hints/InlayHintsProvider.kt @@ -1,4 +1,4 @@ -// Copyright 2000-2022 JetBrains s.r.o. and contributors. Use of this source code is governed by the Apache 2.0 license. +// Copyright 2000-2023 JetBrains s.r.o. and contributors. Use of this source code is governed by the Apache 2.0 license. package com.intellij.codeInsight.hints import com.intellij.lang.Language @@ -39,22 +39,24 @@ enum class InlayGroup(val key: String, @Nls val description: String? = null) { * ATTENTION! Consider using [com.intellij.codeInsight.hints.declarative.InlayHintsProvider] whenever possible! * It is order of magnitude faster, much simpler and less error-prone. This class is very likely to be deprecated in the future. * - * Provider of inlay hints for single language. If you need to create hints for multiple languages, please use [InlayHintsProviderFactory]. + * Provider of inlay hints for a single language. If you need to create hints for multiple languages, use [InlayHintsProviderFactory]. * Both block and inline hints collection are supported. - * Block hints draws between lines of code text. Inline ones are placed on the code text line (like parameter hints) + * Block hints are drawn between lines of code text. Inline ones are placed on the code text line (like parameter hints). + * + * To test it, you may use [com.intellij.testFramework.utils.inlays.InlayHintsProviderTestCase]. + * + * Mark as [com.intellij.openapi.project.DumbAware] to enable it in dumb mode. * * @param T settings type of this provider, if no settings required, please, use [NoSettings] * @see com.intellij.openapi.editor.InlayModel.addInlineElement * @see com.intellij.openapi.editor.InlayModel.addBlockElement - * - * To test it you may use InlayHintsProviderTestCase. - * Mark as [com.intellij.openapi.project.DumbAware] to enable it in dumb mode. */ @JvmDefaultWithCompatibility interface InlayHintsProvider { /** - * If this method is called, provider is enabled for this file - * Warning! Your collector should not use any settings besides [settings] + * If this method is called, the provider is enabled for this file. + * + * Warning: The collector should not use any settings besides [settings]. */ fun getCollectorFor(file: PsiFile, editor: Editor, settings: T, sink: InlayHintsSink): InlayHintsCollector? @@ -66,7 +68,7 @@ interface InlayHintsProvider { fun getPlaceholdersCollectorFor(file: PsiFile, editor: Editor, settings: T, sink: InlayHintsSink): InlayHintsCollector? = null /** - * Settings must be plain java object, fields of these settings will be copied via serialization. + * Settings must be a plain Java object - fields of these settings will be copied via serialization. * Must implement `equals` method, otherwise settings won't be able to track modification. * Returned object will be used to create configurable and collector. * It persists automatically. @@ -76,8 +78,9 @@ interface InlayHintsProvider { @get:Nls(capitalization = Nls.Capitalization.Sentence) /** - * Name of this kind of hints. It will be used in settings and in context menu. - * Please, do not use word "hints" to avoid duplication + * Name of this kind of hints. + * It will be used in settings and in the context menu. + * Do not use the word "hints" to avoid duplication. */ val name: String @@ -186,7 +189,7 @@ interface ChangeListener { } /** - * This class should be used if provider should not have settings. If you use e.g. [Unit] you will have annoying warning in logs. + * This class should be used if the provider should not have settings. If you use e.g. [Unit] you will have annoying warning in logs. */ @Property(assertIfNoBindings = false) class NoSettings { diff --git a/platform/lang-api/src/com/intellij/codeInsight/hints/declarative/InlayTreeSink.kt b/platform/lang-api/src/com/intellij/codeInsight/hints/declarative/InlayTreeSink.kt index 07a29c3d9861..bc82cca60e1f 100644 --- a/platform/lang-api/src/com/intellij/codeInsight/hints/declarative/InlayTreeSink.kt +++ b/platform/lang-api/src/com/intellij/codeInsight/hints/declarative/InlayTreeSink.kt @@ -1,4 +1,4 @@ -// Copyright 2000-2022 JetBrains s.r.o. and contributors. Use of this source code is governed by the Apache 2.0 license. +// Copyright 2000-2023 JetBrains s.r.o. and contributors. Use of this source code is governed by the Apache 2.0 license. package com.intellij.codeInsight.hints.declarative /** @@ -22,7 +22,7 @@ interface InlayTreeSink { } /** - * The payload for the whole inlay, may be used later by the actions from the right-click menu. + * The payload for the whole inlay. It may be used later by the actions from the right-click menu. */ class InlayPayload(val payloadName: String, val payload: InlayActionPayload) diff --git a/platform/lang-impl/src/com/intellij/codeInsight/codeVision/CodeVisionProvider.kt b/platform/lang-impl/src/com/intellij/codeInsight/codeVision/CodeVisionProvider.kt index 7c69c5422207..1f9189f09d47 100644 --- a/platform/lang-impl/src/com/intellij/codeInsight/codeVision/CodeVisionProvider.kt +++ b/platform/lang-impl/src/com/intellij/codeInsight/codeVision/CodeVisionProvider.kt @@ -12,11 +12,12 @@ import org.jetbrains.annotations.ApiStatus import org.jetbrains.annotations.Nls /** - * If invalidation and calculation should be bound to daemon, then use @see [com.intellij.codeInsight.hints.codeVision.DaemonBoundCodeVisionProvider] - * Otherwise implement [CodeVisionProvider] directly + * If invalidation and calculation should be bound to daemon, + * then use [com.intellij.codeInsight.hints.codeVision.DaemonBoundCodeVisionProvider] + * Otherwise implement [CodeVisionProvider] directly. * * If you want to implement multiple providers with same meaning (for example, for different languages) - * and group them in settings window, then @see [com.intellij.codeInsight.codeVision.settings.CodeVisionGroupSettingProvider] + * and group them in the settings window, then see [com.intellij.codeInsight.codeVision.settings.CodeVisionGroupSettingProvider]. * @see [PlatformCodeVisionIds] * @see CodeVisionProviderFactory */ @@ -40,19 +41,19 @@ interface CodeVisionProvider { } /** - * Computes some data on UI thread, before the background thread invocation + * Computes some data on UI thread before the background thread invocation. */ fun precomputeOnUiThread(editor: Editor): T /** - * Called during code vision update process - * Return true if [computeForEditor] should be called - * false otherwise + * Called during the code vision update process. + * + * @return true if [computeForEditor] should be called, false otherwise */ fun shouldRecomputeForEditor(editor: Editor, uiData: T?): Boolean = true /** - * Should return text ranges and applicable hints for them, invoked on background thread. + * Returns text ranges and applicable hints for them, invoked on background thread. * * Note that this method is not executed under read action. */ @@ -60,53 +61,54 @@ interface CodeVisionProvider { fun computeForEditor(editor: Editor, uiData: T): List> = emptyList() /** - * Should return text ranges and applicable hints for them, invoked on background thread. + * Returns text ranges and applicable hints for them, invoked on background thread. * * Note that this method is not executed under read action. */ fun computeCodeVision(editor: Editor, uiData: T): CodeVisionState = CodeVisionState.Ready(computeForEditor(editor, uiData)) - /** - * Handle click on a lens at given range - * [java.awt.event.MouseEvent] accessible with [codeVisionEntryMouseEventKey] data key from [CodeVisionEntry] + /** + * Handles click on a lens at a given range. + * + * [java.awt.event.MouseEvent] is accessible with [codeVisionEntryMouseEventKey] data key from [CodeVisionEntry]. */ fun handleClick(editor: Editor, textRange: TextRange, entry: CodeVisionEntry){ if (entry is CodeVisionPredefinedActionEntry) entry.onClick(editor) } /** - * Handle click on an extra action on a lens at a given range + * Handles click on an extra action on a lens at a given range. */ fun handleExtraAction(editor: Editor, textRange: TextRange, actionId: String): Unit = Unit fun getPlaceholderCollector(editor: Editor, psiFile: PsiFile?) : CodeVisionPlaceholderCollector? = null /** - * User-visible name + * User-visible name. */ @get:Nls val name: String /** - * Used for the default sorting of providers + * Used for the default sorting of providers. */ val relativeOrderings: List /** - * Specifies default anchor for this provider + * Specifies default anchor for this provider. */ val defaultAnchor: CodeVisionAnchorKind /** - * Internal id + * Internal ID. */ val id: String /** - * Uses to group provider in settings panel and to share same behavior (like position and ext.) and description + * Used to group provider in the settings panel and to share same behavior (like position and ext.) and description. + * To group different provider implement [com.intellij.codeInsight.codeVision.settings.CodeVisionGroupSettingProvider]. * @see PlatformCodeVisionIds - * To group different provider implement @see [com.intellij.codeInsight.codeVision.settings.CodeVisionGroupSettingProvider] */ val groupId: String get() = id