diff --git a/platform/core-api/src/com/intellij/openapi/module/ModuleServiceManager.java b/platform/core-api/src/com/intellij/openapi/module/ModuleServiceManager.java
index ad7e3b7265e6..59e3027ea779 100644
--- a/platform/core-api/src/com/intellij/openapi/module/ModuleServiceManager.java
+++ b/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 {
diff --git a/platform/projectModel-api/src/com/intellij/openapi/roots/ModuleExtension.java b/platform/projectModel-api/src/com/intellij/openapi/roots/ModuleExtension.java
index 7f5a2319066c..83af5e35cde3 100644
--- a/platform/projectModel-api/src/com/intellij/openapi/roots/ModuleExtension.java
+++ b/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");