From 8bede1eb6cd218e05960fe435a0f5cc630b2818b Mon Sep 17 00:00:00 2001
From: "Svetlana.Zemlyanskaya" <svetlana.zemlyanskaya@jetbrains.com>
Date: Thu, 25 Oct 2018 15:06:54 +0200
Subject: [PATCH] FUS: add documentation for fus logger

---
 .../statistic/eventLog/FeatureUsageLogger.kt  | 30 +++++++++++++++++++
 1 file changed, 30 insertions(+)

diff --git a/platform/platform-api/src/com/intellij/internal/statistic/eventLog/FeatureUsageLogger.kt b/platform/platform-api/src/com/intellij/internal/statistic/eventLog/FeatureUsageLogger.kt
index b0d7ed9552be..5dffe319a046 100644
--- a/platform/platform-api/src/com/intellij/internal/statistic/eventLog/FeatureUsageLogger.kt
+++ b/platform/platform-api/src/com/intellij/internal/statistic/eventLog/FeatureUsageLogger.kt
@@ -4,6 +4,22 @@ package com.intellij.internal.statistic.eventLog
 import com.intellij.openapi.application.ApplicationManager
 import java.io.File
 
+/**
+ * An entrypoint class to record in event log an information about feature usages.
+ *
+ * There are two types of events:
+ * 1) Regular events, recorded when they occur, e.g. open project, invoked action;
+ * 2) State events, should be recorded regularly by scheduler, e.g. configured libraries/frameworks;
+ *
+ * Each event might be recorded together with an additional (context) information, e.g. source and shortcut for action.
+ *
+ * Note: FeatureUsageCollector API use this class under the hood.
+ * Therefore, if you record statistic with FeatureUsageCollector API there's no need to record events in event log manually.
+ *
+ * @see com.intellij.internal.statistic.service.fus.collectors.FeatureUsagesCollector
+ * @see com.intellij.internal.statistic.service.fus.collectors.ApplicationUsageTriggerCollector
+ * @see com.intellij.internal.statistic.service.fus.collectors.ProjectUsageTriggerCollector
+ */
 object FeatureUsageLogger {
   private val ourLogger : FeatureUsageEventLogger
 
@@ -16,18 +32,32 @@ object FeatureUsageLogger {
     }
   }
 
+  /**
+   * Records that in a group with 'recorderId' (e.g. 'dialogs', 'intentions') a new event occurred.
+   */
   fun log(recorderId: String, action: String) {
     return ourLogger.log(recorderId, action, false)
   }
 
+  /**
+   * Records that in a group with 'recorderId' (e.g. 'dialogs', 'intentions') a new event occurred.
+   * Adds context information to the event, e.g. source and shortcut for an action.
+   */
   fun log(recorderId: String, action: String, data: Map<String, Any>) {
     return ourLogger.log(recorderId, action, data, false)
   }
 
+  /**
+   * Records a new state event in a group with 'recorderId' (e.g. 'run.configuration.type').
+   */
   fun logState(recorderId: String, action: String) {
     return ourLogger.log(recorderId, action, true)
   }
 
+  /**
+   * Records a new state event in a group with 'recorderId' (e.g. 'run.configuration.type').
+   * Adds context information to the event, e.g. if configuration is stored on project or on IDE level.
+   */
   fun logState(recorderId: String, action: String, data: Map<String, Any>) {
     return ourLogger.log(recorderId, action, data, true)
   }