statistics service: convert plain comments to javadoc comments

Javadocs are visible in 'Quick Documentation' popup on a reference, there is no need to navigate to declarations so see them, also they support proper links to other classes and rich formatting.

platform/platform-impl/src/com/intellij/internal/statistic/service/fus/FUStatisticsSettingsService.java

@@ -10,10 +10,14 @@ import org.jetbrains.annotations.NotNull;
 import java.util.Collections;
 import java.util.Set;
 
-// this service connects to jetbrains.com resources and requests actual info about running statistics services
-// 1. url: where to post statistics data.
-// 2. white-list-service: WhiteListService url: this service returns approved UsagesCollectors(groups)
-// 3. permitted: true/false. statistics could be stopped remotely. if false UsageCollectors won't be started
+/**
+ * This service connects to jetbrains.com resources and requests actual info about running statistics services
+ * <ul>
+ * <li> url: where to post statistics data.
+ * <li> white-list-service: WhiteListService url: this service returns approved UsagesCollectors(groups)
+ * <li> permitted: true/false. statistics could be stopped remotely. if false UsageCollectors won't be started
+ * </ul>
+ */
 public class FUStatisticsSettingsService extends StatisticsConnectionService {
   private static final String APPROVED_GROUPS_SERVICE = "white-list-service";
   public  static FUStatisticsSettingsService getInstance() {return  new FUStatisticsSettingsService();}

platform/platform-impl/src/com/intellij/internal/statistic/service/fus/FUStatisticsWhiteListGroupsService.java

@@ -12,18 +12,27 @@ import java.util.Collections;
 import java.util.Set;
 import java.util.stream.Collectors;
 
-// 1. Statistics service (FUStatisticsService) collects data ONLY from approved  usages collectors(FeatureUsagesCollector)
-// 2. Approved collectors could be requested online.
-// 3. This service (FUStatisticsWhiteListGroupsService) connects to online JB service  and requests  "approved" UsagesCollectors(groups)
-// 4. Online JB service  returns  result in json file format:
-//   {
-//    "groups" : [{
-//      "id" : "statistics.Productivity",
-//      "builds" : [{ "from" : "173.4127.37" }]
-//    }, {
-//      "id" : "spring-example"
-//    }]
-//  }
+/**
+ * <ol>
+ * <li> Statistics service ({@link FUStatisticsService}) collects data ONLY from approved  usages collectors ({@link com.intellij.internal.statistic.service.fus.collectors.FeatureUsagesCollector})
+ * <li> Approved collectors could be requested online.
+ * <li> This service ({@link FUStatisticsWhiteListGroupsService}) connects to online JB service and requests "approved" UsagesCollectors(groups).
+ * <li> Online JB service  returns  result in json file format:
+ * <pre>{@code
+ * {
+ * "groups" : [
+ *   {
+ *    "id" : "statistics.Productivity",
+ *    "builds" : [{ "from" : "173.4127.37" }]
+ *   },
+ *   {
+ *    "id" : "spring-example"
+ *   }
+ *  ]
+ * }
+ * }</pre>
+ * </ol>
+ */
 public class FUStatisticsWhiteListGroupsService {
   private static final Logger LOG =
     Logger.getInstance("com.intellij.internal.statistic.service.whiteList.FUStatisticsWhiteListGroupsService");

platform/platform-impl/src/com/intellij/internal/statistic/service/fus/collectors/ApplicationUsageTriggerCollector.java

@@ -8,16 +8,21 @@ import org.jetbrains.annotations.NotNull;
 import java.util.Map;
 import java.util.Set;
 
-// see example:
-// public final class MyApplicationActionsUsageTriggerCollector extends ApplicationUsageTriggerCollector {
-//    public static void record(@NotNull String metric) {
-//       FUSApplicationUsageTrigger.getInstance().trigger(MyApplicationActionsUsageTriggerCollector.class, metric);
-//   }
-//
-//   public String getGroupId() { return "statistics.my.application.actions";}
-//  }
-//  in any place of code write: MyApplicationActionsUsageTriggerCollector.record("my.cool.action.performed");
-
+/**
+ * See example:
+ * <pre>{@code
+ * public final class MyApplicationActionsUsageTriggerCollector extends ApplicationUsageTriggerCollector {
+ *   public static void record(@NotNull String metric) {
+ *     FUSApplicationUsageTrigger.getInstance().trigger(MyApplicationActionsUsageTriggerCollector.class, metric);
+ *   }
+ *
+ *   public String getGroupId() {
+ *     return "statistics.my.application.actions";
+ *   }
+ * }
+ * }</pre>
+ * In any place of code write: {@code MyApplicationActionsUsageTriggerCollector.record("my.cool.action.performed");}
+ */
 public abstract class ApplicationUsageTriggerCollector extends ApplicationUsagesCollector implements FUStatisticsDifferenceSender {
   @NotNull
   @Override

platform/platform-impl/src/com/intellij/internal/statistic/service/fus/collectors/ApplicationUsagesCollector.java

@@ -2,7 +2,6 @@
 package com.intellij.internal.statistic.service.fus.collectors;
 
 import com.intellij.ide.plugins.cl.PluginClassLoader;
-import com.intellij.internal.statistic.CollectUsagesException;
 import com.intellij.internal.statistic.beans.UsageDescriptor;
 import com.intellij.openapi.extensions.ExtensionPointName;
 import org.jetbrains.annotations.NotNull;
@@ -12,7 +11,9 @@ import java.util.Collections;
 import java.util.Set;
 import java.util.stream.Collectors;
 
-// see ProjectUsagesCollector class
+/**
+ * @see ProjectUsagesCollector
+ */
 public abstract class ApplicationUsagesCollector extends FeatureUsagesCollector {
   private static final ExtensionPointName<ApplicationUsagesCollector> EP_NAME =
     ExtensionPointName.create("com.intellij.statistics.applicationUsagesCollector");

platform/platform-impl/src/com/intellij/internal/statistic/service/fus/collectors/FUStatisticsDifferenceSender.java

@@ -1,19 +1,22 @@
 // Copyright 2000-2018 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license that can be found in the LICENSE file.
 package com.intellij.internal.statistic.service.fus.collectors;
 
-// some FeatureUsagesCollector can implement markup interface FUStatisticsDifferenceSender.
-// such collectors post "difference" value metrics.
-// for such collectors we persist sent data(between send sessions)
-// and merge metrics (actualValue = actualValueFromCollector - persistedValue)
-// "difference" value example: we want to know "how many times MyAction was invoked".
-//   1. my.foo.MyCollector(implements FUStatisticsDifferenceSender) calculates
-//      common invocations and returns "myAction.invokes"=N where N is total invocations count.
-//   2. first send: action was totally invoked 17 times. my.foo.MyCollector returns 17 .
-//      we send "myAction.invokes"=17
-//   3. second send: action was totally invoked 30 times. my.foo.MyCollector returns 30.
-//      action was invoked 13 times from the previous send.
-//      we send "myAction.invokes"=13
-//   4. third send: action was totally invoked 30 times. my.foo.MyCollector returns 30.
-//      action was not invoked from the previous send. we send NOTHING.
+/**
+ * Implement this markup interface in {@link FeatureUsagesCollector}'s implementation to post "difference" value metrics.
+ * For such collectors we persist sent data (between send sessions)
+ * and merge metrics (actualValue = actualValueFromCollector - persistedValue).
+ * "difference" value example: we want to know "how many times MyAction was invoked".
+ * <ol>
+ * <li> my.foo.MyCollector(implements FUStatisticsDifferenceSender) calculates
+ * common invocations and returns "myAction.invokes"=N where N is total invocations count.
+ * <li> First send: action was totally invoked 17 times. my.foo.MyCollector returns 17.
+ * We send "myAction.invokes"=17.
+ * <li> Second send: action was totally invoked 30 times. my.foo.MyCollector returns 30.
+ * Action was invoked 13 times from the previous send.
+ * We send "myAction.invokes"=13.
+ * <li> Third send: action was totally invoked 30 times. my.foo.MyCollector returns 30.
+ * Action was not invoked from the previous send. We send NOTHING.
+ * </ol>
+ */
 public interface FUStatisticsDifferenceSender {
 }

platform/platform-impl/src/com/intellij/internal/statistic/service/fus/collectors/FUStatisticsPersistence.java

@@ -24,7 +24,7 @@ import java.nio.file.attribute.BasicFileAttributes;
 import java.util.Map;
 import java.util.Set;
 
-// persists ProjectUsagesCollector data between user sessions (project + IJ build)
+/** Persists ProjectUsagesCollector data between user sessions (project + IJ build) */
 public class FUStatisticsPersistence {
   private static final Logger
     LOG = Logger.getInstance("com.intellij.internal.statistic.service.fus.collectors.FUStatisticsPersistence");
@@ -34,11 +34,13 @@ public class FUStatisticsPersistence {
   private static final String SENT_DATA_FILE = "fus-sent-data.json";
   public static final String FUS_CACHE_PATH = "fus-sessions";
 
-  // 1. this method is regularly  invoked by the statistics scheduler (see StatisticsJobsScheduler) to persist statistics data  for current project.
-  // 2. persisted data will be used by statistics service if this project isn't available at the statistics sending time
-  // 3.  method requests actual "approved" usages collectors (see FUStatisticsWhiteListGroupsService) to be invoked.
-  //     if FUStatisticsWhiteListGroupsService is OFFLINE the data will NOT collected.
-  // 4. collected data are persisted in system cache. one file for one project session. the session is pair: project + IJ build number
+  /**
+   * This method is regularly invoked by the statistics scheduler (see StatisticsJobsScheduler) to persist statistics data for current project.
+   * Persisted data will be used by statistics service if this project isn't available at the statistics sending time
+   * Method requests actual "approved" usages collectors (see FUStatisticsWhiteListGroupsService) to be invoked.
+   * if FUStatisticsWhiteListGroupsService is OFFLINE the data will NOT collected.
+   * Collected data are persisted in system cache. One file for one project session. The session is pair: project + IJ build number
+   */
   public static String persistProjectUsages(@NotNull Project project) {
     Set<String> groups = FUStatisticsSettingsService.getInstance().getApprovedGroups();
     if (groups.isEmpty() && !ApplicationManagerEx.getApplicationEx().isInternal()) return null;
@@ -60,8 +62,8 @@ public class FUStatisticsPersistence {
     return fileName;
   }
 
+  /** Iterates system cache persisted session files and converts json file content to FSSession format */
   @NotNull
-  // this method iterates system cache persisted session files and convert json file content to FSSession format
   public static Set<FSSession> getPersistedSessions() {
     Set<FSSession> persistedSessions = ContainerUtil.newHashSet();
     File statisticsCacheDir = getStatisticsSystemCacheDirectory();
@@ -85,10 +87,12 @@ public class FUStatisticsPersistence {
     return persistedSessions;
   }
 
-  // Statistics service (FUStatisticsService) collects and sends data.
-  // if this data is accepted by online JB statistics service (response status is "ok")
-  // persisted sessions cache must be cleaned to avoid  repeatable sending.
-  // This method cleans obsolete statistics persisted data (files)
+  /**
+   * Statistics service (FUStatisticsService) collects and sends data.
+   * If this data is accepted by online JB statistics service (response status is "ok")
+   * persisted sessions cache must be cleaned to avoid  repeatable sending.
+   * This method cleans obsolete statistics persisted data (files).
+   */
   public static void clearSessionPersistence(long dataTime) {
     File statisticsCacheDir = getStatisticsSystemCacheDirectory();
     if (statisticsCacheDir != null) {

platform/platform-impl/src/com/intellij/internal/statistic/service/fus/collectors/FUStatisticsStateService.java

@@ -20,20 +20,10 @@ public class FUStatisticsStateService implements UsagesCollectorConsumer {
     return new FUStatisticsStateService();
   }
 
-  // some FeatureUsagesCollector can implement markup interface FUStatisticsDifferenceSender.
-  // such collectors post "difference" value metrics.
-  // for such collectors we persist sent data(between send sessions)
-  // and merge metrics (actualValue = actualValueFromCollector - persistedValue)
-  // "difference" value example: we want to know "how many times MyAction was invoked".
-  //   1. my.foo.MyCollector(implements FUStatisticsDifferenceSender) calculates
-  //      common invocations and returns "myAction.invokes"=N where N is total invocations count.
-  //   2. first send: action was totally invoked 17 times. my.foo.MyCollector returns 17 .
-  //      we send "myAction.invokes"=17
-  //   3. second send: action was totally invoked 30 times. my.foo.MyCollector returns 30.
-  //      action was invoked 13 times from the previous send.
-  //      we send "myAction.invokes"=13
-  //   4. third send: action was totally invoked 30 times. my.foo.MyCollector returns 30.
-  //      action was not invoked from the previous send. we send NOTHING.
+  /**
+   * Returns data in JSON format. For collectors implementing {@link FUStatisticsDifferenceSender} the difference between the actual and
+   * persisted data is included.
+   */
   @Nullable
   public String getMergedDataToSend(@NotNull String actualDataFromCollectors, @NotNull Set<String> approvedGroups) {
     @NotNull FSContent allDataFromCollectors = FSContent.fromJson(actualDataFromCollectors);

platform/platform-impl/src/com/intellij/internal/statistic/service/fus/collectors/ProjectUsageTriggerCollector.java

@@ -8,17 +8,22 @@ import org.jetbrains.annotations.NotNull;
 
 import java.util.Map;
 import java.util.Set;
-// see example:
-// class MyProjectActionUsageTriggerCollector: ProjectUsageTriggerCollector() {
-//  override fun getGroupId(): String = MY_GROUP_ID
-//
-//  companion object {
-//    fun trigger(project: Project, featureId: String) {
-//      FUSProjectUsageTrigger.getInstance(project).trigger(MyProjectActionUsageTriggerCollector::class.java, featureId)
-//    }}}
-//
-//  and invoke it:  MyProjectActionUsageTriggerCollector.trigger(project, "my.action.performed")
 
+/**
+ * See example:
+ * <pre>{@code
+ * class MyProjectActionUsageTriggerCollector: ProjectUsageTriggerCollector() {
+ *   override fun getGroupId(): String = MY_GROUP_ID
+
+ *   companion object {
+ *     fun trigger(project: Project, featureId: String) {
+ *       FUSProjectUsageTrigger.getInstance(project).trigger(MyProjectActionUsageTriggerCollector::class.java, featureId)
+ *     }
+ *   }
+ * }
+ * }</pre>
+ * and invoke it: {@code MyProjectActionUsageTriggerCollector.trigger(project, "my.action.performed")}
+ */
 public abstract class ProjectUsageTriggerCollector extends ProjectUsagesCollector implements FUStatisticsDifferenceSender {
   @NotNull
   @Override

platform/platform-impl/src/com/intellij/internal/statistic/service/fus/collectors/ProjectUsagesCollector.java

@@ -2,7 +2,6 @@
 package com.intellij.internal.statistic.service.fus.collectors;
 
 import com.intellij.ide.plugins.cl.PluginClassLoader;
-import com.intellij.internal.statistic.CollectUsagesException;
 import com.intellij.internal.statistic.beans.UsageDescriptor;
 import com.intellij.openapi.extensions.ExtensionPointName;
 import com.intellij.openapi.project.Project;
@@ -13,7 +12,7 @@ import java.util.Collections;
 import java.util.Set;
 import java.util.stream.Collectors;
 
-//see ApplicationUsagesCollector class
+/** @see ApplicationUsagesCollector */
 public abstract class ProjectUsagesCollector extends FeatureUsagesCollector {
   private static final ExtensionPointName<ProjectUsagesCollector> EP_NAME =
     ExtensionPointName.create("com.intellij.statistics.projectUsagesCollector");

platform/platform-impl/src/com/intellij/internal/statistic/service/fus/collectors/UsagesCollectorConsumer.java

@@ -1,7 +1,8 @@
 // Copyright 2000-2018 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license that can be found in the LICENSE file.
 package com.intellij.internal.statistic.service.fus.collectors;
 
-// markup interface.
-// UsageCollector extentions could be requested only by UsagesCollectorConsumer
+/**
+ * Markup interface for classes which are allowed to request data from {@link FeatureUsagesCollector}.
+ */
 interface UsagesCollectorConsumer {
 }