Extensive cleanup

editor_basics/src/main/java/org/intellij/sdk/editor/EditorAreaIllustration.java

@@ -10,31 +10,42 @@ import com.intellij.openapi.ui.Messages;
 import java.util.List;
 
 /**
+ * If conditions support it, makes a menu visible to display information
+ * about the caret.
  * @author Anna Bulenkova
+ * @see com.intellij.openapi.actionSystem.AnAction
  */
 public class EditorAreaIllustration extends AnAction {
+  
+  /**
+   * Displays a message with information about the current caret.
+   * @param e  Event related to this action
+   */
   @Override
-  public void actionPerformed(AnActionEvent anActionEvent) {
-    final Editor editor = anActionEvent.getRequiredData(CommonDataKeys.EDITOR);
+  public void actionPerformed(AnActionEvent e) {
+    // Get access to the editor and caret model. update() validated editor's existence.
+    final Editor editor = e.getRequiredData(CommonDataKeys.EDITOR);
     CaretModel caretModel = editor.getCaretModel();
-    boolean caretModelUpToDate = caretModel.isUpToDate();
+    // Getting the primary caret ensures we get the right one of a possible many.
     Caret primaryCaret = caretModel.getPrimaryCaret();
-    boolean primaryCaretIsValid = primaryCaret.isValid();
+    // Build and display the caret report.
     StringBuilder report = new StringBuilder();
-    if ( caretModelUpToDate && primaryCaretIsValid ) {
-      report.append(primaryCaret.getLogicalPosition().toString() + "\n" );
-      report.append(primaryCaret.getVisualPosition().toString() + "\n" );
-      report.append("Offset: " + primaryCaret.getOffset() );
-    } else {
-      report.append("Caret model up to date: " + caretModelUpToDate + "\n" + "Primary Caret is valid: " + primaryCaretIsValid);
-    }
-    Messages.showInfoMessage(report.toString(),"Caret Parameters Inside The Editor");
+    report.append(primaryCaret.getLogicalPosition().toString() + "\n");
+    report.append(primaryCaret.getVisualPosition().toString() + "\n");
+    report.append("Offset: " + primaryCaret.getOffset());
+    Messages.showInfoMessage(report.toString(), "Caret Parameters Inside The Editor");
   }
   
+  /**
+   * Sets visibility of this action menu item if:
+   *   A project is open,
+   *   An editor is active,
+   * @param e  Event related to this action
+   */
   @Override
   public void update(AnActionEvent e) {
     //Get required data keys
-    final Project project = e.getData(CommonDataKeys.PROJECT);
+    final Project project = e.getProject();
     final Editor editor = e.getData(CommonDataKeys.EDITOR);
     //Set visibility only in case of existing project and editor
     e.getPresentation().setVisible(project != null && editor != null);

editor_basics/src/main/java/org/intellij/sdk/editor/EditorHandlerIllustration.java

@@ -9,24 +9,59 @@ import com.intellij.openapi.project.Project;
 import org.jetbrains.annotations.NotNull;
 
 /**
+ * Menu action to clone a new caret based on an existing one.
  * @author Anna Bulenkova
+ * @see com.intellij.openapi.actionSystem.AnAction
  */
 public class EditorHandlerIllustration extends AnAction {
+  
+  /**
+   * This block of static code does not pertain to this class.
+   * It registers the custom MyTypedHandler, an TypedActionHandler
+   * that handles actions activated by typing in the editor.
+   * This registration code just needs to appear in a class (like AnAction class)
+   * that gets instantiated as part of IntelliJ startup.
+   */
+  static {
+    final EditorActionManager actionManager = EditorActionManager.getInstance();
+    final TypedAction typedAction = actionManager.getTypedAction();
+    typedAction.setupHandler(new MyTypedHandler());
+  }
+  
+  /**
+   * Clones a new caret at a higher Logical Position line number.
+   * @param e  Event related to this action
+   */
   @Override
-  public void actionPerformed(@NotNull AnActionEvent anActionEvent) {
-    final Editor editor = anActionEvent.getRequiredData(CommonDataKeys.EDITOR);
+  public void actionPerformed(@NotNull AnActionEvent e) {
+    // Editor is known to exist from update, so it's not null
+    final Editor editor = e.getRequiredData(CommonDataKeys.EDITOR);
+    // Get the action manager in order to get the necessary action handler...
     EditorActionManager actionManager = EditorActionManager.getInstance();
-    //Insert one more caret below the active caret
+    // Get the action handler registered to clone carets
     EditorActionHandler actionHandler = actionManager.getActionHandler(IdeActions.ACTION_EDITOR_CLONE_CARET_BELOW);
-    actionHandler.execute(editor, editor.getCaretModel().getCurrentCaret(), anActionEvent.getDataContext());
+    // Clone one caret below the active caret
+    actionHandler.execute(editor, editor.getCaretModel().getPrimaryCaret(), e.getDataContext());
   }
-
+  
+  /**
+   * Sets visibility of this action menu item if:
+   *   A project is open,
+   *   An editor is active,
+   *   At least one caret exists
+   * @param e  Event related to this action
+   */
   @Override
-  public void update(@NotNull final AnActionEvent anActionEvent) {
+  public void update(@NotNull final AnActionEvent e) {
+    boolean visibility = false;
     //Set visible if at least one caret is available
-    final Project project = anActionEvent.getData(CommonDataKeys.PROJECT);
-    final Editor editor = anActionEvent.getData(CommonDataKeys.EDITOR);
-    anActionEvent.getPresentation()
-                 .setVisible((project != null && editor != null && !editor.getCaretModel().getAllCarets().isEmpty()));
+    final Project project = e.getProject();
+    final Editor editor = e.getData(CommonDataKeys.EDITOR);
+    if (editor != null && project != null) {
+      // Ensure the list of carets in the editor is not empty
+      visibility = !editor.getCaretModel().getAllCarets().isEmpty();
+    }
+    e.getPresentation().setVisible(visibility);
   }
+  
 }

editor_basics/src/main/java/org/intellij/sdk/editor/EditorIllustration.java

@@ -9,41 +9,49 @@ import com.intellij.openapi.editor.actionSystem.*;
 import com.intellij.openapi.project.Project;
 
 /**
+ * Menu action to replace a selection of characters with a fixed string.
  * @author Anna Bulenkova
+ * @see com.intellij.openapi.actionSystem.AnAction
  */
 public class EditorIllustration extends AnAction {
-
-  static {
-    final EditorActionManager actionManager = EditorActionManager.getInstance();
-    final TypedAction typedAction = actionManager.getTypedAction();
-    typedAction.setupHandler(new MyTypedHandler());
-  }
-
+  
+  /**
+   * Replaces the run of text selected by the primary caret with a fixed string.
+   * @param e  Event related to this action
+   */
   @Override
   public void actionPerformed(final AnActionEvent e) {
     //Get all the required data from data keys
+    // Editor and Project were verified in update(), so they are not null.
     final Editor editor = e.getRequiredData(CommonDataKeys.EDITOR);
     final Project project = e.getRequiredData(CommonDataKeys.PROJECT);
-    //Access document, caret, and selection
     final Document document = editor.getDocument();
-    // Get information about the selection
-    final SelectionModel selectionModel = editor.getSelectionModel();
-    final int start = selectionModel.getSelectionStart();
-    final int end = selectionModel.getSelectionEnd();
-    //Make the replacement with the name of this plugin
+    // Work off of the primary caret to get the selection info
+    Caret primaryCaret = editor.getCaretModel().getPrimaryCaret();
+    int start = primaryCaret.getSelectionStart();
+    int end = primaryCaret.getSelectionEnd();
+    // Replace the selection with a fixed string.
+    // Must do this document change in a write action context.
     WriteCommandAction.runWriteCommandAction(project, () ->
-        document.replaceString(start, end, "Replaced by editor_basics")
+        document.replaceString(start, end, "editor_basics")
     );
     // De-select the text range that was just replaced
-    selectionModel.removeSelection();
+    primaryCaret.removeSelection();
   }
-
+  
+  /**
+   * Sets visibility of this action menu item if:
+   *   A project is open,
+   *   An editor is active,
+   *   Some characters are selected
+   * @param e  Event related to this action
+   */
   @Override
   public void update(final AnActionEvent e) {
     //Get required data keys
     final Project project = e.getProject();
     final Editor editor = e.getData(CommonDataKeys.EDITOR);
-    //Set visibility only in case of existing project and editor and if some text in the editor is selected
+    //Set visibility only in case of existing project and editor and if a selection exists
     e.getPresentation().setVisible((project != null && editor != null && editor.getSelectionModel().hasSelection()));
   }
 }

editor_basics/src/main/java/org/intellij/sdk/editor/MyTypedHandler.java

@@ -10,14 +10,23 @@ import com.intellij.openapi.project.Project;
 import org.jetbrains.annotations.NotNull;
 
 /**
+ * This is a custom TypedActionHandler that handles actions activated
+ * keystrokes in the editor.
+ * The execute method inserts a fixed string at Offset 0 of the document.
+ * Document changes are made in the context of a write action.
+ * MyTypedHandler is registered by static code in the EditorHandlerIllustration class.
  * @author Anna Bulenkova
+ * @see com.intellij.openapi.editor.actionSystem.TypedActionHandler
  */
 class MyTypedHandler implements TypedActionHandler {
   @Override
   public void execute(@NotNull Editor editor, char c, @NotNull DataContext dataContext) {
+    // Get the document and project
     final Document document = editor.getDocument();
     Project project = editor.getProject();
-    Runnable runnable = () -> document.insertString(0, "Inserted by editor_basics\n");
+    // Construct the runnable to substitute the string at offset 0 in the document
+    Runnable runnable = () -> document.insertString(0, "editor_basics\n");
+    // Make the document change in the context of a write action.
     WriteCommandAction.runWriteCommandAction(project, runnable);
   }
 }