From cf9de7effe87805f2d5bac8f7a222b500e8c8e44 Mon Sep 17 00:00:00 2001
From: Nicolay Mitropolsky <nicolay.mitropolsky@jetbrains.com>
Date: Wed, 9 Oct 2024 21:24:50 +0200
Subject: [PATCH] [service-view] IJPL-163799 draft javadoc for the
 ServiceViewDescriptor and ServiceViewDescriptor

GitOrigin-RevId: a4135d769fcf4112dda5cf430cf74edbedcc35d8
---
 .../execution/services/ServiceViewContributor.java    | 11 +++++++++++
 .../execution/services/ServiceViewDescriptor.java     |  7 +++++++
 2 files changed, 18 insertions(+)

diff --git a/platform/lang-api/src/com/intellij/execution/services/ServiceViewContributor.java b/platform/lang-api/src/com/intellij/execution/services/ServiceViewContributor.java
index 98a1929a6113..bc144adb9ceb 100644
--- a/platform/lang-api/src/com/intellij/execution/services/ServiceViewContributor.java
+++ b/platform/lang-api/src/com/intellij/execution/services/ServiceViewContributor.java
@@ -8,6 +8,14 @@ import org.jetbrains.annotations.Nullable;
 
 import java.util.List;
 
+/// Implementation of this interface represents a (parent) node in the Service View Tree that could have multiple child nodes.
+/// Top root [ServiceViewContributor]-s should be registered as a `serviceViewContributor` extension-point.
+/// Nested [ServiceViewContributor]-s are returned by the [#getServices(Project)] of the parent.
+///
+/// @param <T> domain model type of children, if for instance, the Service View represents a list of connections to a server
+///                       then [T] is a single connection. If [T] implements [ServiceViewContributor] then it would have a nested tree inside
+/// @see ServiceViewDescriptor
+/// @see ServiceViewManager
 public interface ServiceViewContributor<T> {
   ExtensionPointName<ServiceViewContributor<?>> CONTRIBUTOR_EP_NAME =
     ExtensionPointName.create("com.intellij.serviceViewContributor");
@@ -16,12 +24,15 @@ public interface ServiceViewContributor<T> {
     return CONTRIBUTOR_EP_NAME.findExtension(contributorClass);
   }
 
+  /// @return a [ServiceViewDescriptor] for this (parent) node
   @NotNull
   ServiceViewDescriptor getViewDescriptor(@NotNull Project project);
 
+  /// @return list of child domain model entities, contained in this [ServiceViewContributor]
   @NotNull
   List<T> getServices(@NotNull Project project);
 
+  /// @return a [ServiceViewDescriptor] for the child node [T]
   @NotNull
   ServiceViewDescriptor getServiceDescriptor(@NotNull Project project, @NotNull T service);
 }
diff --git a/platform/lang-api/src/com/intellij/execution/services/ServiceViewDescriptor.java b/platform/lang-api/src/com/intellij/execution/services/ServiceViewDescriptor.java
index 3c819694777d..00388e0dce77 100644
--- a/platform/lang-api/src/com/intellij/execution/services/ServiceViewDescriptor.java
+++ b/platform/lang-api/src/com/intellij/execution/services/ServiceViewDescriptor.java
@@ -15,8 +15,15 @@ import javax.swing.*;
 import java.awt.event.MouseEvent;
 import java.util.List;
 
+/// Implementation of this interface represents a node in the Service View.
+/// It provides information on how the node will be represented in the Service View Tree (by the [#getPresentation()]) method,
+/// how it should be shown in the detail panel (be the [#getContentComponent()])
+///  and available actions ([#getPopupActions()] and [#getToolbarActions()])
+///
 /// Subclasses could also implement the [UiDataProvider] to provide the [DataContext]
 /// for the actions returned by [#getToolbarActions()] and [#getPopupActions()]
+///
+/// @see ServiceViewContributor
 public interface ServiceViewDescriptor {
   Key<Boolean> ACTION_HOLDER_KEY = Key.create("ServiceViewActionHolderContentComponent");