// Copyright 2000-2019 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.openapi.components;

import com.intellij.openapi.util.Getter;
import org.jetbrains.annotations.ApiStatus;
import org.jetbrains.annotations.NotNull;

import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;

/**
 * @see <a href="http://www.jetbrains.org/intellij/sdk/docs/basics/persisting_state_of_components.html">Persisting States</a>
 */
@Retention(RetentionPolicy.RUNTIME)
public @interface State {
  /**
   * Component name.
   */
  @NotNull
  String name();

  /**
   * <p>Storages specification.</p>
   *
   * <p>Project-level: optional, standard project file will be used by default
   * ({@code *.ipr} file for file-based and
   * {@code .idea/misc.xml} for directory-based).</p>
   *
   * <p>Module-level: optional, corresponding module file will be used ({@code *.iml}).</p>
   */
  @NotNull
  Storage[] storages() default {};

  /**
   * If set to false, complete project (or application) reload is required when the storage file is changed externally and the state has changed.
   */
  boolean reloadable() default true;

  /**
   * If true, default state will be loaded from resources (if exists).
   */
  boolean defaultStateAsResource() default false;

  /**
   * Additional export path (relative to application-level configuration root directory).
   */
  String additionalExportFile() default "";

  Class<? extends NameGetter> presentableName() default NameGetter.class;

  /**
   * Is this component intended to store data only in the external storage.
   */
  boolean externalStorageOnly() default false;

  /**
   * If true and statistics is enabled, values of boolean fields will be recorded.
   */
  boolean reportStatistic() default false;

  @ApiStatus.Experimental
  boolean useLoadedStateAsExisting() default true;

  abstract class NameGetter implements Getter<String> {
  }
}

@@ -1724,85 +1724,564 @@
   * 
-If true and statistics is enabled, values of boolean fields will be recorded.
+%3Cp%3EEnables recording of boolean and numerical fields, if true and statistics is allowed.%3C/p%3E%0A   * %3Cbr/%3E%0A   * %3Cp%3EBoolean: records not default value of the field.%3C/p%3E%0A   * %3Cp%3ENumerical: records an event that the value is not default.%0A   * To record an absolute value of the field, add %7B@link ReportValue%7D annotation. %3C/p%3E%0A   *%0A   * %3Cbr/%3E%0A   * %3Ci%3ELimitations:%3C/i%3E%3Cul%3E%0A   * %3Cli%3EWon't record the value of object, string or enum fields.%3C/li%3E%0A   * %3Cli%3EWon't record fields if state is persisted manually, i.e. the state is %7B@link org.jdom.Element%7D %3C/li%3E%0A   * %3C/ul%3E
 %0A   

add more documentation for 'reportStatistics' property