From 2772baf23fd10f20522297d0e17626bfd3638546 Mon Sep 17 00:00:00 2001
From: Dmitry Batkovich <dmitry.batkovich@jetbrains.com>
Date: Fri, 5 May 2017 11:04:36 +0300
Subject: [PATCH] properties: add javadoc

---
 .../intellij/lang/properties/IProperty.java   |  4 +--
 .../lang/properties/psi/PropertiesFile.java   | 27 ++++++++++++++++++-
 .../lang/properties/psi/Property.java         |  4 +++
 3 files changed, 32 insertions(+), 3 deletions(-)

diff --git a/plugins/properties/properties-psi-api/src/com/intellij/lang/properties/IProperty.java b/plugins/properties/properties-psi-api/src/com/intellij/lang/properties/IProperty.java
index 0ff27cea63c7..e0c06450d8a9 100644
--- a/plugins/properties/properties-psi-api/src/com/intellij/lang/properties/IProperty.java
+++ b/plugins/properties/properties-psi-api/src/com/intellij/lang/properties/IProperty.java
@@ -27,8 +27,8 @@ import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 
 /**
- * @author Dmitry Avdeev
- *         Date: 7/25/11
+ * An interface representing a generic property. It can be a property inside xml file or a property inside .properties-file
+ *
  */
 public interface IProperty extends Navigatable, Iconable {
   DataKey<IProperty[]> ARRAY_KEY = DataKey.create("IProperty.array");
diff --git a/plugins/properties/properties-psi-api/src/com/intellij/lang/properties/psi/PropertiesFile.java b/plugins/properties/properties-psi-api/src/com/intellij/lang/properties/psi/PropertiesFile.java
index aa2597d96d37..c8376f0f45cf 100644
--- a/plugins/properties/properties-psi-api/src/com/intellij/lang/properties/psi/PropertiesFile.java
+++ b/plugins/properties/properties-psi-api/src/com/intellij/lang/properties/psi/PropertiesFile.java
@@ -38,6 +38,11 @@ import java.util.List;
 import java.util.Locale;
 import java.util.Map;
 
+/**
+ * An interface representing a properties file.
+ *
+ * It can be both xml based {@link com.intellij.lang.properties.xml.XmlPropertiesFile} or .properties based
+ */
 public interface PropertiesFile {
 
   @NotNull
@@ -81,6 +86,9 @@ public interface PropertiesFile {
   /**
    * Adds property to the the file after the specified property.
    * If anchor is null, property added to the beginning of the file.
+   *
+   * In the most cases one can consider to use {@link PropertiesFile#addPropertyAfter(String, String, IProperty)} instead of this method
+   *
    * @param property to add. Typically you create the property via {@link PropertiesElementFactory}.
    * @param anchor property after which to add the new property
    * @return newly added property.
@@ -89,9 +97,20 @@ public interface PropertiesFile {
    */
   @NotNull PsiElement addPropertyAfter(@NotNull IProperty property, @Nullable IProperty anchor) throws IncorrectOperationException;
 
+  /**
+   * Adds property to the the file after the specified property.
+   * If anchor is null, property added to the beginning of the file.
+   *
+   * @param key of a property to add.
+   * @param value of a property to add.
+   * @param anchor property after which to add the new property
+   * @return newly added property.
+   * @throws IncorrectOperationException
+   */
+  IProperty addPropertyAfter(String key, String value, IProperty anchor) throws IncorrectOperationException;
+
   IProperty addProperty(String key, String value);
 
-  IProperty addPropertyAfter(String key, String value, IProperty anchor);
   /**
    * @return Property key to the property value map.
    * Do not modify this map. It's no use anyway.
@@ -102,11 +121,17 @@ public interface PropertiesFile {
 
   VirtualFile getVirtualFile();
 
+  /**
+   * @return containing directory for the corresponding properties file
+   */
   PsiDirectory getParent();
 
   Project getProject();
 
   String getText();
 
+  /**
+   * @return true if property keys in file are alphabetically sorted, otherwise returns false
+   */
   boolean isAlphaSorted();
 }
diff --git a/plugins/properties/properties-psi-api/src/com/intellij/lang/properties/psi/Property.java b/plugins/properties/properties-psi-api/src/com/intellij/lang/properties/psi/Property.java
index 289d9ebc38e4..f9b602f525eb 100644
--- a/plugins/properties/properties-psi-api/src/com/intellij/lang/properties/psi/Property.java
+++ b/plugins/properties/properties-psi-api/src/com/intellij/lang/properties/psi/Property.java
@@ -28,6 +28,10 @@ import com.intellij.psi.PsiNamedElement;
 import com.intellij.psi.StubBasedPsiElement;
 
 /**
+ * An interface representing a property inside .properties based properties files
+ *
+ * @see PropertiesFile
+ * @see IProperty
  * @see PropertiesElementFactory
  */
 public interface Property extends PsiNamedElement, StubBasedPsiElement<PropertyStub>, NavigatablePsiElement, IProperty {