properties: add javadoc

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");

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();
 }

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 {