From 1ffc98f81e1a4a517f9630db6d7ba7f2f3c3f7ba Mon Sep 17 00:00:00 2001 From: nik Date: Mon, 16 Jul 2018 11:25:37 +0300 Subject: [PATCH] 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. --- .../fus/FUStatisticsSettingsService.java | 12 ++++--- .../FUStatisticsWhiteListGroupsService.java | 33 ++++++++++++------- .../ApplicationUsageTriggerCollector.java | 25 ++++++++------ .../ApplicationUsagesCollector.java | 5 +-- .../FUStatisticsDifferenceSender.java | 31 +++++++++-------- .../collectors/FUStatisticsPersistence.java | 26 ++++++++------- .../collectors/FUStatisticsStateService.java | 18 +++------- .../ProjectUsageTriggerCollector.java | 25 ++++++++------ .../collectors/ProjectUsagesCollector.java | 3 +- .../collectors/UsagesCollectorConsumer.java | 5 +-- 10 files changed, 102 insertions(+), 81 deletions(-) diff --git a/platform/platform-impl/src/com/intellij/internal/statistic/service/fus/FUStatisticsSettingsService.java b/platform/platform-impl/src/com/intellij/internal/statistic/service/fus/FUStatisticsSettingsService.java index 69c06fcbf958..2be66c968b99 100644 --- a/platform/platform-impl/src/com/intellij/internal/statistic/service/fus/FUStatisticsSettingsService.java +++ b/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 + * + */ public class FUStatisticsSettingsService extends StatisticsConnectionService { private static final String APPROVED_GROUPS_SERVICE = "white-list-service"; public static FUStatisticsSettingsService getInstance() {return new FUStatisticsSettingsService();} diff --git a/platform/platform-impl/src/com/intellij/internal/statistic/service/fus/FUStatisticsWhiteListGroupsService.java b/platform/platform-impl/src/com/intellij/internal/statistic/service/fus/FUStatisticsWhiteListGroupsService.java index d3f9cfaf75de..bfe3ce24ee70 100644 --- a/platform/platform-impl/src/com/intellij/internal/statistic/service/fus/FUStatisticsWhiteListGroupsService.java +++ b/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" -// }] -// } +/** + *
    + *
  1. Statistics service ({@link FUStatisticsService}) collects data ONLY from approved usages collectors ({@link com.intellij.internal.statistic.service.fus.collectors.FeatureUsagesCollector}) + *
  2. Approved collectors could be requested online. + *
  3. This service ({@link FUStatisticsWhiteListGroupsService}) connects to online JB service and requests "approved" UsagesCollectors(groups). + *
  4. Online JB service returns result in json file format: + * 
    {@code
+ * {
+ * "groups" : [
+ *   {
+ *    "id" : "statistics.Productivity",
+ *    "builds" : [{ "from" : "173.4127.37" }]
+ *   },
+ *   {
+ *    "id" : "spring-example"
+ *   }
+ *  ]
+ * }
+ * }
    + *
+ */ public class FUStatisticsWhiteListGroupsService { private static final Logger LOG = Logger.getInstance("com.intellij.internal.statistic.service.whiteList.FUStatisticsWhiteListGroupsService"); diff --git a/platform/platform-impl/src/com/intellij/internal/statistic/service/fus/collectors/ApplicationUsageTriggerCollector.java b/platform/platform-impl/src/com/intellij/internal/statistic/service/fus/collectors/ApplicationUsageTriggerCollector.java index 3df49a6707b4..1fd2d1c45523 100644 --- a/platform/platform-impl/src/com/intellij/internal/statistic/service/fus/collectors/ApplicationUsageTriggerCollector.java +++ b/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: + * 
{@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";
+ *   }
+ * }
+ * }
+ * In any place of code write: {@code MyApplicationActionsUsageTriggerCollector.record("my.cool.action.performed");} + */ public abstract class ApplicationUsageTriggerCollector extends ApplicationUsagesCollector implements FUStatisticsDifferenceSender { @NotNull @Override diff --git a/platform/platform-impl/src/com/intellij/internal/statistic/service/fus/collectors/ApplicationUsagesCollector.java b/platform/platform-impl/src/com/intellij/internal/statistic/service/fus/collectors/ApplicationUsagesCollector.java index 2e0d17ff4081..4db7a57c1e16 100644 --- a/platform/platform-impl/src/com/intellij/internal/statistic/service/fus/collectors/ApplicationUsagesCollector.java +++ b/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 EP_NAME = ExtensionPointName.create("com.intellij.statistics.applicationUsagesCollector"); diff --git a/platform/platform-impl/src/com/intellij/internal/statistic/service/fus/collectors/FUStatisticsDifferenceSender.java b/platform/platform-impl/src/com/intellij/internal/statistic/service/fus/collectors/FUStatisticsDifferenceSender.java index dea72962a76b..0a3b4ffc38d6 100644 --- a/platform/platform-impl/src/com/intellij/internal/statistic/service/fus/collectors/FUStatisticsDifferenceSender.java +++ b/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". + *
    + *
  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. + *
+ */ public interface FUStatisticsDifferenceSender { } diff --git a/platform/platform-impl/src/com/intellij/internal/statistic/service/fus/collectors/FUStatisticsPersistence.java b/platform/platform-impl/src/com/intellij/internal/statistic/service/fus/collectors/FUStatisticsPersistence.java index 54383f6f8cfd..dcaff4b00f9e 100644 --- a/platform/platform-impl/src/com/intellij/internal/statistic/service/fus/collectors/FUStatisticsPersistence.java +++ b/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 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 getPersistedSessions() { Set 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) { diff --git a/platform/platform-impl/src/com/intellij/internal/statistic/service/fus/collectors/FUStatisticsStateService.java b/platform/platform-impl/src/com/intellij/internal/statistic/service/fus/collectors/FUStatisticsStateService.java index 0a44338cce18..0dec592ee833 100644 --- a/platform/platform-impl/src/com/intellij/internal/statistic/service/fus/collectors/FUStatisticsStateService.java +++ b/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 approvedGroups) { @NotNull FSContent allDataFromCollectors = FSContent.fromJson(actualDataFromCollectors); diff --git a/platform/platform-impl/src/com/intellij/internal/statistic/service/fus/collectors/ProjectUsageTriggerCollector.java b/platform/platform-impl/src/com/intellij/internal/statistic/service/fus/collectors/ProjectUsageTriggerCollector.java index de1cb3349f1b..aee2ba62e31c 100644 --- a/platform/platform-impl/src/com/intellij/internal/statistic/service/fus/collectors/ProjectUsageTriggerCollector.java +++ b/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: + * 
{@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)
+ *     }
+ *   }
+ * }
+ * }
+ * and invoke it: {@code MyProjectActionUsageTriggerCollector.trigger(project, "my.action.performed")} + */ public abstract class ProjectUsageTriggerCollector extends ProjectUsagesCollector implements FUStatisticsDifferenceSender { @NotNull @Override diff --git a/platform/platform-impl/src/com/intellij/internal/statistic/service/fus/collectors/ProjectUsagesCollector.java b/platform/platform-impl/src/com/intellij/internal/statistic/service/fus/collectors/ProjectUsagesCollector.java index 3547688a52ad..2e26c51825db 100644 --- a/platform/platform-impl/src/com/intellij/internal/statistic/service/fus/collectors/ProjectUsagesCollector.java +++ b/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 EP_NAME = ExtensionPointName.create("com.intellij.statistics.projectUsagesCollector"); diff --git a/platform/platform-impl/src/com/intellij/internal/statistic/service/fus/collectors/UsagesCollectorConsumer.java b/platform/platform-impl/src/com/intellij/internal/statistic/service/fus/collectors/UsagesCollectorConsumer.java index 4255cceb2431..20c56a3ad965 100644 --- a/platform/platform-impl/src/com/intellij/internal/statistic/service/fus/collectors/UsagesCollectorConsumer.java +++ b/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 { }