diff --git a/platform/projectModel-api/src/com/intellij/openapi/projectRoots/SdkAdditionalData.java b/platform/projectModel-api/src/com/intellij/openapi/projectRoots/SdkAdditionalData.java
index 115d21162acd..be60e1b5da1d 100644
--- a/platform/projectModel-api/src/com/intellij/openapi/projectRoots/SdkAdditionalData.java
+++ b/platform/projectModel-api/src/com/intellij/openapi/projectRoots/SdkAdditionalData.java
@@ -2,27 +2,30 @@
 package com.intellij.openapi.projectRoots;
 
 /**
- * The `SdkAdditionalData` interface represents additional data associated with an SDK.
- * This interface should be implemented by classes that need to provide additional data for an SDK.
+ * Represents additional data associated with an SDK.
+ * Should be implemented by classes that need to provide additional data for an {@link Sdk}.
  * <p>
- * It's possible to create an object from scratch or update it via [SdkModificator]. Changing already
- * atached to the SDK object outside of the [SdkModificator] is prohibited to catch all plases where
- * you have mutations outside the modificator, implement [markAsCommited] or use [SdkAdditionalDataBase]
- * as a base class for your class and add [SdkAdditionalDataBase#assertWritable()] to all your setter
- * methods.
+ * It's possible to create an object from scratch or update it via {@link SdkModificator}.
+ * Changing an instance already attached to the SDK outside of the {@code SdkModificator} is prohibited
+ * to catch all places where state is changed outside the modificator.
+ * <p>
+ * Implement {@link #markAsCommited()} or use {@link com.intellij.openapi.projectRoots.impl.SdkAdditionalDataBase SdkAdditionalDataBase}
+ * as a base class and add {@link com.intellij.openapi.projectRoots.impl.SdkAdditionalDataBase#assertWritable() SdkAdditionalDataBase#assertWritable()}
+ * to all setter methods.
  */
 public interface SdkAdditionalData {
   /**
-   * Invocation of this method indicates that additional data must become read-only and report errors on attempt to make changes. Any changes
-   * made after won't be persisted and going to be discarded after the next sdk update.
-   * To make proper additional data modification, you should:<ul>
-   * <li>Obtain sdk modificator using {@link Sdk#getSdkModificator()}</li>
+   * Invocation of this method indicates that additional data must become read-only and report errors on attempt to make changes.
+   * Any changes made after won't be persisted and will be discarded after the next SDK update.
+   * <p>>
+   * To make proper additional data modification:<ul>
+   * <li>Obtain {@link SdkModificator} via {@link Sdk#getSdkModificator()}</li>
    * <li>Obtain additional data from the modificator using {@link SdkModificator#getSdkAdditionalData()} / set new additional data using {@link SdkModificator#setSdkAdditionalData(SdkAdditionalData)}</li>
    * <li>Make any modifications to the additional data</li>
    * <li>Commit modificator using {@link SdkModificator#commitChanges()}</li>
    * </ul>
    *
-   * @implSpec any additional data is expected to be writable after creation and become read only after invoking this method.
+   * @implSpec any additional data is expected to be writable after creation and becomes read only after invoking this method.
    */
   default void markAsCommited() { }
 }