platform: added javadoc for ModuleExtension and moduleService

platform/core-api/src/com/intellij/openapi/module/ModuleServiceManager.java

@@ -23,6 +23,18 @@ import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 
 /**
+ * Provide a module service if you need to can be used to store data associated with a module. Its implementation should be registered in plugin.xml:
+ * <pre>
+ * &lt;extensions defaultExtensionNs="com.intellij"&gt;
+ *   &lt;moduleService serviceInterface="qualified-interface-class-name"
+                    serviceImplementation="qualified-implementation-class-name"/&gt;
+ * &lt;/extensions&gt;
+ * </pre>
+ * Class is loaded and its instance is created lazily when {@link #getService(Module, Class)} method is called for the first time.
+ * <p/>
+ * If the service implementation class implements {@link com.intellij.openapi.components.PersistentStateComponent} interface its state will
+ * be persisted in the module configuration file.
+ *
  * @author yole
  */
 public class ModuleServiceManager {

platform/projectModel-api/src/com/intellij/openapi/roots/ModuleExtension.java

@@ -22,7 +22,11 @@ import org.jdom.Element;
 import org.jetbrains.annotations.NotNull;
 
 /**
- * Implement {@link com.intellij.openapi.components.PersistentStateComponent} to be serializable.
+ * Extend this class to provide additional module-level properties which can be edited in Project Structure dialog. For ordinary module-level
+ * properties use {@link com.intellij.openapi.module.ModuleServiceManager module service} instead.
+ * <p/>
+ * If the inheritor implements {@link com.intellij.openapi.components.PersistentStateComponent} its state will be persisted in the module
+ * configuration file.
  */
 public abstract class ModuleExtension implements Disposable {
   public static final ExtensionPointName<ModuleExtension> EP_NAME = ExtensionPointName.create("com.intellij.moduleExtension");