[Macros] Code review feedback

Change-Id: Ia75f1ba568d14b8978867a955d1b970397f548de
Signed-off-by: Fabio Zadrozny <fabiofz@gmail.com>

28 files changed, 428 insertions, 208 deletions

diff --git a/bundles/org.eclipse.e4.core.macros/src/org/eclipse/e4/core/macros/EMacroService.java b/bundles/org.eclipse.e4.core.macros/src/org/eclipse/e4/core/macros/EMacroService.java
index 3ca040ef..f1044b79 100644
--- a/bundles/org.eclipse.e4.core.macros/src/org/eclipse/e4/core/macros/EMacroService.java
+++ b/bundles/org.eclipse.e4.core.macros/src/org/eclipse/e4/core/macros/EMacroService.java
@@ -28,7 +28,7 @@ package org.eclipse.e4.core.macros;
  * instructions through {@link #addMacroInstruction(IMacroInstruction)}.
  * </p>
  * <p>
- * It's also important to note that any macro instruction added through
+ * It is also important to note that any macro instruction added through
  * addMacroInstruction also needs to have an {@link IMacroInstructionFactory}
  * registered through the org.eclipse.e4.core.macros.macroInstructionsFactory
  * extension point (with a match through
@@ -38,25 +38,31 @@ package org.eclipse.e4.core.macros;
 public interface EMacroService {
 
 	/**
-	 * @return whether a macro is currently being recorded (note that it's possible
-	 *         for the user to start recording and then playback a macro
-	 *         simultaneously -- although the inverse is not true).
+	 * Return {@code true} when a macro is currently being recorded. Note that it is
+	 * possible for the user to playback a macro while recording, although the
+	 * inverse is not true.
+	 *
+	 * @return {@code true} when a macro is currently being recorded.
 	 */
 	boolean isRecording();
 
 	/**
-	 * @return whether a macro is currently being played back.
+	 * Return {@code true} when a macro is being played back and {@code false} if
+	 * there is no macro being played back.
+	 *
+	 * @return {code true} when a macro is currently being played back.
 	 */
 	boolean isPlayingBack();
 
 	/**
-	 * Adds a macro instruction to be added to the current macro being recorded. Any
-	 * macro instruction added also needs to have an
-	 * {@link IMacroInstructionFactory} registered through the
-	 * org.eclipse.e4.core.macros.macroInstructionsFactory extension point (with a
-	 * match through {@link org.eclipse.e4.core.macros.IMacroInstruction#getId()})
+	 * Adds a macro instruction to be added to the current macro being recorded.
+	 * Each type of macro instruction must have an {@link IMacroInstructionFactory}
+	 * registered through the
+	 * {@code org.eclipse.e4.core.macros.macroInstructionsFactory} extension point
+	 * (with a match through
+	 * {@link org.eclipse.e4.core.macros.IMacroInstruction#getId()})
 	 *
-	 * Does nothing if there's no macro being currently recorded.
+	 * This method is a no-op when no macro being currently recorded.
 	 *
 	 * @param macroInstruction
 	 *            the macro instruction to be added to the macro currently being
@@ -70,50 +76,50 @@ public interface EMacroService {
 
 	/**
 	 * Adds a macro instruction to be added to the current macro being recorded.
-	 * This method should be used when an event may trigger the creation of
-	 * multiple macro instructions but only one of those should be recorded.
+	 * This method should be used when an event may trigger the creation of multiple
+	 * macro instructions but only one of those should be recorded.
 	 *
 	 * For instance, if a given {@code KeyDown} event is recorded in a
-	 * {@link StyledText} and later an action is triggered by this event, the
+	 * {@code StyledText} and later an action is triggered by this event, the
 	 * recorded action should overwrite the {@code KeyDown} event.
 	 *
 	 * @param macroInstruction
 	 *            the macro instruction to be added to the macro currently being
 	 *            recorded.
 	 * @param event
-	 *            the event that triggered the creation of the macro instruction
-	 *            to be added. If there are multiple macro instructions added
-	 *            for the same event, only the one with the highest priority
-	 *            will be kept (if 2 events have the same priority, the last one
-	 *            will replace the previous one).
+	 *            the event that triggered the creation of the macro instruction to
+	 *            be added. If there are multiple macro instructions added for the
+	 *            same event, only the one with the highest priority will be kept
+	 *            (if 2 events have the same priority, the last one will replace the
+	 *            previous one).
 	 * @param priority
-	 *            the priority of the macro instruction being added (to be
-	 *            compared against the priority of other added macro
-	 *            instructions for the same event).
+	 *            the priority of the macro instruction being added (to be compared
+	 *            against the priority of other added macro instructions for the
+	 *            same event).
 	 * @see #addMacroInstruction(IMacroInstruction)
 	 */
 	void addMacroInstruction(IMacroInstruction macroInstruction, Object event, int priority);
 
 	/**
-	 * Toggles the macro record mode (i.e.: if it's currently not recording, starts
-	 * recording a macro, otherwise, stops the current record -- at which point a
-	 * macro should be saved with what was recorded so far).
-	 *
-	 * Note that when playing back, calling toggleMacroRecord() should do nothing
-	 * (while it's Ok to start recording and then playback a previous macro to add
-	 * previously recorded macro instructions to the current macro, the opposite is
-	 * not true).
+	 * Toggles the macro record mode: if currently not recording, starts recording a
+	 * macro, otherwise stops the current recording and saves the macro.
+	 *
+	 * Note that calling {@link #toggleMacroRecord()} does nothing during play back.
+	 * Although it is possible to start recording and then replay a previous macro,
+	 * so as to add previously recorded macro instructions to the current macro, the
+	 * opposite is not true.
 	 */
 	void toggleMacroRecord();
 
 	/**
 	 * Plays back the last recorded macro.
 	 *
-	 * Note: it's Ok to call it while a macro is being recorded (which should
-	 * playback the given macro and add its contents to the new macro being
-	 * recorded).
+	 * Note that is is possible to call this method when recording a macro so as to
+	 * add the previously recorded macro instructions to the current macro being
+	 * recorded.
 	 *
 	 * @throws MacroPlaybackException
+	 *             if some error happened while recording the macro.
 	 */
 	void playbackLastMacro() throws MacroPlaybackException;
 
@@ -133,14 +139,20 @@ public interface EMacroService {
 	void removeMacroStateListener(IMacroStateListener listener);
 
 	/**
-	 * @return the macro record context created when macro record started or null if
-	 *         it's not currently recording.
+	 * Provides the macro record context or null if the macro engine is not
+	 * recording.
+	 *
+	 * @return the macro record context created when macro record started or
+	 *         {@code null} if not currently recording.
 	 */
 	IMacroRecordContext getMacroRecordContext();
 
 	/**
+	 * Provides the macro playback context or null if the macro engine is not
+	 * playing back.
+	 *
 	 * @return the macro playback context created when the macro playback started or
-	 *         null if it's not currently playing back.
+	 *         {@code null} if not currently playing back.
 	 */
 	IMacroPlaybackContext getMacroPlaybackContext();
 
@@ -148,22 +160,34 @@ public interface EMacroService {
 	// (by default should load the command behavior
 	// through the org.eclipse.e4.core.macros.commandHandling extension
 	// point,
-	// but it's possible to programmatically change it as needed later on).
+	// but it is possible to programmatically change it as needed later on).
 
 	/**
+	 * Returns {@code true} if the given Eclipse Core Command should be recorded and
+	 * {@code false} otherwise. This specifically means that when a given Eclipse
+	 * Core Command is executed, a macro instruction will be created for it.
+	 * Likewise, if {@code false} is returned, a macro instruction will not be
+	 * created automatically (and as such, it won't be recorded in the macro). See
+	 * the {@code org.eclipse.e4.core.macros.commandHandling} extension point for
+	 * details.
+	 *
 	 * @param commandId
 	 *            the id of the Eclipse Core Command.
 	 *
-	 * @return whether the command should be recorded for playback when recording a
-	 *         macro (i.e.: an {@link org.eclipse.e4.core.macros.IMacroInstruction}
-	 *         will be automatically created to play it back when in record mode).
+	 * @return whether the given Eclipse Core Command should be recorded for
+	 *         playback when recording a macro (i.e.: an
+	 *         {@link org.eclipse.e4.core.macros.IMacroInstruction} will be
+	 *         automatically created to play it back when in record mode).
 	 *
-	 * @see org.eclipse.e4.core.macros.commandHandling extension point
 	 */
-	@SuppressWarnings("javadoc")
-	boolean isCommandRecorded(String commandId);
+	boolean getRecordCommandInMacro(String commandId);
 
 	/**
+	 * Sets whether a given Eclipse Core Command should have a macro instruction
+	 * added automatically while recording a macro (by default, all commands are
+	 * recorded, so, this is commonly used to disable the recording of some
+	 * command).
+	 *
 	 * @param commandId
 	 *            the Eclipse Core Command id to be customized during macro
 	 *            record/playback.
@@ -175,9 +199,8 @@ public interface EMacroService {
 	 *            automatically created to play it back when in record mode. If
 	 *            false, the activation of the command will not be recorded.
 	 *
-	 * @see org.eclipse.e4.core.macros.commandHandling extension point
+	 * @see {@code org.eclipse.e4.core.macros.commandHandling} extension point
 	 */
-	@SuppressWarnings("javadoc")
 	void setRecordCommandInMacro(String commandId, boolean recordInMacro);
 
 	/**
diff --git a/bundles/org.eclipse.e4.core.macros/src/org/eclipse/e4/core/macros/IMacroContext.java b/bundles/org.eclipse.e4.core.macros/src/org/eclipse/e4/core/macros/IMacroContext.java
index ef6a318b..101c348c 100644
--- a/bundles/org.eclipse.e4.core.macros/src/org/eclipse/e4/core/macros/IMacroContext.java
+++ b/bundles/org.eclipse.e4.core.macros/src/org/eclipse/e4/core/macros/IMacroContext.java
@@ -19,6 +19,9 @@ package org.eclipse.e4.core.macros;
 public interface IMacroContext {
 
 	/**
+	 * Gets a value for a given key stored in the macro context or null if it's not
+	 * available.
+	 *
 	 * @param key
 	 *            the key of the variable to be retrieved.
 	 * @return the object related to that variable.
@@ -26,6 +29,9 @@ public interface IMacroContext {
 	public Object get(String key);
 
 	/**
+	 * Sets a value to a given key, which may be later retrieved through
+	 * {@link #get(String)}.
+	 *
 	 * @param key
 	 *            the key of the variable to store.
 	 * @param value
diff --git a/bundles/org.eclipse.e4.core.macros/src/org/eclipse/e4/core/macros/IMacroInstruction.java b/bundles/org.eclipse.e4.core.macros/src/org/eclipse/e4/core/macros/IMacroInstruction.java
index 6c9b0005..e3648aa7 100644
--- a/bundles/org.eclipse.e4.core.macros/src/org/eclipse/e4/core/macros/IMacroInstruction.java
+++ b/bundles/org.eclipse.e4.core.macros/src/org/eclipse/e4/core/macros/IMacroInstruction.java
@@ -19,11 +19,12 @@ import java.util.Map;
 public interface IMacroInstruction {
 
 	/**
+	 * Returns the id to be used for the macro instruction. This id may be visible
+	 * to the user, so it should be something short and readable (such as
+	 * {@code KeyDown}, or {@code Command}). Note that an id cannot be changed
+	 * afterwards as this id may be written to disk.
+	 *
 	 * @return the id for the macro instruction.
-	 * @note This id may be visible to the user so it should ideally be
-	 *       something short and readable (such as {@code KeyDown}, or
-	 *       {@code Command}). Note that an id cannot be changed afterwards as
-	 *       this id may be written to disk.
 	 */
 	String getId();
 
@@ -38,14 +39,14 @@ public interface IMacroInstruction {
 	void execute(IMacroPlaybackContext macroPlaybackContext) throws MacroPlaybackException;
 
 	/**
-	 * Convert the macro instruction into a map (which may be later dumped to the
-	 * disk) and recreated with an
-	 * {@link org.eclipse.e4.core.macros.IMacroInstructionFactory} registered
-	 * through the org.eclipse.e4.core.macros.macroInstructionsFactory extension
+	 * Converts the macro instruction into a map for serialization, that can be
+	 * used to recreate the macro instruction with an
+	 * {@link IMacroInstructionFactory} registered through the
+	 * {@code org.eclipse.e4.core.macros.macroInstructionsFactory} extension
 	 * point.
 	 *
-	 * @return a map which may be dumped to the disk and can be used to recreate the
-	 *         macro instruction later on.
+	 * @return a map that may be serialized and that can be used to recreate the
+	 *         macro instruction
 	 */
 	Map<String, String> toMap();
 
diff --git a/bundles/org.eclipse.e4.core.macros/src/org/eclipse/e4/core/macros/IMacroInstructionFactory.java b/bundles/org.eclipse.e4.core.macros/src/org/eclipse/e4/core/macros/IMacroInstructionFactory.java
index 330c8696..b03010b0 100644
--- a/bundles/org.eclipse.e4.core.macros/src/org/eclipse/e4/core/macros/IMacroInstructionFactory.java
+++ b/bundles/org.eclipse.e4.core.macros/src/org/eclipse/e4/core/macros/IMacroInstructionFactory.java
@@ -23,6 +23,9 @@ import java.util.Map;
 public interface IMacroInstructionFactory {
 
 	/**
+	 * Creates a macro instruction from a string map obtained from
+	 * {@link IMacroInstruction#toMap()}.
+	 *
 	 * @param stringMap
 	 *            a map which was created from {@link IMacroInstruction#toMap()}
 	 * @return the {@link IMacroInstruction} created from the given stringMap.
diff --git a/bundles/org.eclipse.e4.core.macros/src/org/eclipse/e4/core/macros/MacroPlaybackException.java b/bundles/org.eclipse.e4.core.macros/src/org/eclipse/e4/core/macros/MacroPlaybackException.java
index 9911e090..bbb59743 100644
--- a/bundles/org.eclipse.e4.core.macros/src/org/eclipse/e4/core/macros/MacroPlaybackException.java
+++ b/bundles/org.eclipse.e4.core.macros/src/org/eclipse/e4/core/macros/MacroPlaybackException.java
@@ -11,7 +11,7 @@
 package org.eclipse.e4.core.macros;
 
 /**
- * An exception to be raised if there's some issue when playing back macros.
+ * An exception to be raised if there is some issue when playing back macros.
  */
 public class MacroPlaybackException extends Exception {
 
diff --git a/bundles/org.eclipse.e4.core.macros/src/org/eclipse/e4/core/macros/internal/ComposableMacro.java b/bundles/org.eclipse.e4.core.macros/src/org/eclipse/e4/core/macros/internal/ComposableMacro.java
index 3828e2d3..0c1c13da 100644
--- a/bundles/org.eclipse.e4.core.macros/src/org/eclipse/e4/core/macros/internal/ComposableMacro.java
+++ b/bundles/org.eclipse.e4.core.macros/src/org/eclipse/e4/core/macros/internal/ComposableMacro.java
@@ -47,7 +47,6 @@ import org.eclipse.e4.core.macros.MacroPlaybackException;
 			fIndex = index;
 			fPriority = priority;
 		}
-
 	}
 
 	/**
@@ -94,25 +93,23 @@ import org.eclipse.e4.core.macros.MacroPlaybackException;
 
 	/**
 	 * Adds a macro instruction to be added to the current macro being recorded.
-	 * This method should be used when an event may trigger the creation of
-	 * multiple macro instructions and only one of those should be recorded.
+	 * This method should be used when an event may trigger the creation of multiple
+	 * macro instructions and only one of those should be recorded.
 	 *
 	 * @param macroInstruction
 	 *            the macro instruction to be added to the macro currently being
 	 *            recorded.
 	 * @param event
-	 *            the event that triggered the creation of the macro instruction
-	 *            to be added. If there are multiple macro instructions added
-	 *            for the same event, only the one with the highest priority
-	 *            will be kept (if 2 events have the same priority, the last one
-	 *            will replace the previous one).
+	 *            the event that triggered the creation of the macro instruction to
+	 *            be added. If there are multiple macro instructions added for the
+	 *            same event, only the one with the highest priority will be kept
+	 *            (if 2 events have the same priority, the last one will replace the
+	 *            previous one).
 	 * @param priority
-	 *            the priority of the macro instruction being added (to be
-	 *            compared against the priority of other added macro
-	 *            instructions for the same event).
-	 * @return true if the macro instruction was actually added and false
-	 *         otherwise.
-	 * @see #addMacroInstruction(IMacroInstruction)
+	 *            the priority of the macro instruction being added (to be compared
+	 *            against the priority of other added macro instructions for the
+	 *            same event).
+	 * @return true if the macro instruction was actually added and false otherwise.
 	 */
 	public boolean addMacroInstruction(IMacroInstruction macroInstruction, Object event, int priority) {
 		Assert.isNotNull(event);
@@ -148,12 +145,11 @@ import org.eclipse.e4.core.macros.MacroPlaybackException;
 	}
 
 	/**
-	 * Actually returns the bytes to be written to the disk to be loaded back
-	 * later on (the actual load and playback is later done by
-	 * {@link SavedJSMacro}).
+	 * Actually returns the bytes to be written to the disk to be loaded back later
+	 * on (the actual load and playback is later done by {@link SavedJSMacro}).
 	 *
-	 * @return an UTF-8 encoded array of bytes which can be used to rerun the
-	 *         macro later on.
+	 * @return an UTF-8 encoded array of bytes which can be used to rerun the macro
+	 *         later on.
 	 */
 	/* default */ byte[] toJSBytes() {
 		final StringBuilder buf = new StringBuilder(fMacroInstructions.size() * 60);
@@ -178,6 +174,9 @@ import org.eclipse.e4.core.macros.MacroPlaybackException;
 	}
 
 	/**
+	 * Provides the number of macro instructions which have been added to this
+	 * macro.
+	 *
 	 * @return the number of macro instructions in this macro.
 	 */
 	public int getLength() {
diff --git a/bundles/org.eclipse.e4.core.macros/src/org/eclipse/e4/core/macros/internal/JSONHelper.java b/bundles/org.eclipse.e4.core.macros/src/org/eclipse/e4/core/macros/internal/JSONHelper.java
index aad71254..cbe44ed8 100644
--- a/bundles/org.eclipse.e4.core.macros/src/org/eclipse/e4/core/macros/internal/JSONHelper.java
+++ b/bundles/org.eclipse.e4.core.macros/src/org/eclipse/e4/core/macros/internal/JSONHelper.java
@@ -19,6 +19,15 @@ import java.util.Map.Entry;
  */
 public class JSONHelper {
 
+	/**
+	 * Quotes contents of the strings so that a given string can be saved as a valid
+	 * JSON string.
+	 *
+	 * @param string
+	 *            the string to be quoted.
+	 * @return a string where the values of the input string are quoted so that it
+	 *         forms a valid JSON string.
+	 */
 	public static String quote(String string) {
 		int len = string.length();
 		if (len == 0) {
@@ -72,9 +81,11 @@ public class JSONHelper {
 	}
 
 	/**
+	 * Provides a JSON representation of the passed map.
+	 *
 	 * @param map
-	 *            a map to be converted to a json string.
-	 * @return a json string with the contents of the passed map.
+	 *            a map to be converted to a JSON string.
+	 * @return a JSON string with the contents of the passed map.
 	 */
 	public static String toJSon(Map<String, String> map) {
 		Iterator<Entry<String, String>> iterator = map.entrySet().iterator();
diff --git a/bundles/org.eclipse.e4.core.macros/src/org/eclipse/e4/core/macros/internal/MacroManager.java b/bundles/org.eclipse.e4.core.macros/src/org/eclipse/e4/core/macros/internal/MacroManager.java
index 0e481c7d..a5b87899 100644
--- a/bundles/org.eclipse.e4.core.macros/src/org/eclipse/e4/core/macros/internal/MacroManager.java
+++ b/bundles/org.eclipse.e4.core.macros/src/org/eclipse/e4/core/macros/internal/MacroManager.java
@@ -55,8 +55,13 @@ public class MacroManager {
 	private int fMaxNumberOfTemporaryMacros = 5;
 
 	/**
+	 * Sets the maximum number of temporary macros (so, if more than
+	 * {@code maxNumberOfTemporaryMacros} are created, the oldest ones will be
+	 * removed until the number of temporary macros equals
+	 * {@code maxNumberOfTemporaryMacros}).
+	 *
 	 * @param maxNumberOfTemporaryMacros
-	 *            The max number of temporary macros to be kept.
+	 *            The max number of temporary macros to be kept (must be >= 1).
 	 */
 	public void setMaxNumberOfTemporaryMacros(int maxNumberOfTemporaryMacros) {
 		Assert.isTrue(maxNumberOfTemporaryMacros >= 1);
@@ -64,7 +69,10 @@ public class MacroManager {
 	}
 
 	/**
-	 * @return Returns the max number of temporary macros to be kept.
+	 * Provides the maximum number of temporary macros to be kept (if there are more
+	 * macros than the value returned, older temporary macros should be removed).
+	 *
+	 * @return the maximum number of temporary macros to be kept.
 	 */
 	public int getMaxNumberOfTemporaryMacros() {
 		return fMaxNumberOfTemporaryMacros;
@@ -117,6 +125,8 @@ public class MacroManager {
 	}
 
 	/**
+	 * Sets the macro directories which should be tracked for macros.
+	 *
 	 * @param macrosDirectories
 	 *            the directories where macros should be looked up. The first
 	 *            directory is the one where macros are persisted. If there are 2
@@ -133,6 +143,9 @@ public class MacroManager {
 	}
 
 	/**
+	 * If there's a macro being currently recorded, {@code true} is returned,
+	 * otherwise, {@code false} is returned.
+	 *
 	 * @return whether a macro is currently being recorded.
 	 */
 	public boolean isRecording() {
@@ -140,6 +153,9 @@ public class MacroManager {
 	}
 
 	/**
+	 * If there's a macro being currently played back, {@code true} is returned,
+	 * otherwise, {@code false} is returned.
+	 *
 	 * @return whether a macro is currently being played back.
 	 */
 	public boolean isPlayingBack() {
@@ -153,6 +169,7 @@ public class MacroManager {
 	 * @param macroInstruction
 	 *            the macro instruction to be recorded.
 	 * @throws CancelMacroRecordingException
+	 *             if the macro recording should be cancelled.
 	 */
 	public void addMacroInstruction(IMacroInstruction macroInstruction) throws CancelMacroRecordingException {
 		ComposableMacro macroBeingRecorded = fMacroBeingRecorded;
@@ -167,9 +184,9 @@ public class MacroManager {
 	/**
 	 * Adds a macro instruction to be added to the current macro being recorded. The
 	 * difference between this method and
-	 * {@link #addMacroInstruction(IMacroInstruction)} is that it's meant to be used
-	 * when an event may trigger the creation of multiple macro instructions and
-	 * only one of those should be recorded.
+	 * {@link #addMacroInstruction(IMacroInstruction)} is that it is meant to be
+	 * used when an event may trigger the creation of multiple macro instructions
+	 * and only one of those should be recorded.
 	 *
 	 * For instance, if a given KeyDown event is recorded in a StyledText and later
 	 * an action is triggered by this event, the recorded action should overwrite
@@ -189,6 +206,7 @@ public class MacroManager {
 	 *            against the priority of other added macro instructions for the
 	 *            same event).
 	 * @throws CancelMacroRecordingException
+	 *             if the macro recording should be cancelled.
 	 * @see #addMacroInstruction(IMacroInstruction)
 	 */
 	public void addMacroInstruction(IMacroInstruction macroInstruction, Object event, int priority)
@@ -288,6 +306,8 @@ public class MacroManager {
 	}
 
 	/**
+	 * Saves a composable macro as a temporary macro on disk.
+	 *
 	 * @param macro
 	 *            the macro to be recorded as a temporary macro.
 	 */
@@ -327,17 +347,20 @@ public class MacroManager {
 	}
 
 	/**
+	 * Provides the path/time for the temporary macros at a given directory as n
+	 * list sorted such that the last element is the oldest one and the first is the
+	 * newest.
+	 *
 	 * @param macroDirectory
 	 *            the directory from where we should get the temporary macros.
 	 *
-	 * @return The path/time for the temporary macros at a given directory as an
-	 *         array list sorted such that the last element is the oldest one and
-	 *         the first is the newest.
+	 * @return the temporary macros available along with their path and creation
+	 *         time
 	 */
 	public List<PathAndTime> listTemporaryMacrosPathAndTime(File macroDirectory) {
-		// It's a sorted list and not a tree map to deal with the case of
+		// It is a sorted list and not a tree map to deal with the case of
 		// multiple times pointing to the same file (although hard to happen,
-		// it's not impossible).
+		// it is not impossible).
 		List<PathAndTime> pathAndTime = new ArrayList<>();
 
 		try (DirectoryStream<Path> directoryStream = Files.newDirectoryStream(Paths.get(macroDirectory.toURI()),
@@ -356,7 +379,7 @@ public class MacroManager {
 			Activator.log(e1);
 		}
 
-		// Sort by reversed modified time (because it's faster to remove the
+		// Sort by reversed modified time (because it is faster to remove the
 		// last element from an ArrayList later on).
 		Collections.sort(pathAndTime, new Comparator<PathAndTime>() {
 
@@ -390,7 +413,7 @@ public class MacroManager {
 	}
 
 	/**
-	 * Playback the last recorded macro.
+	 * Plays back the last recorded macro.
 	 *
 	 * @param macroService
 	 *            the macro service (used to notify listeners of the change.
@@ -452,6 +475,9 @@ public class MacroManager {
 	}
 
 	/**
+	 * Provides the listeners which are currently registered to be notified of
+	 * changes in the macro state.
+	 *
 	 * @return the currently registered listeners.
 	 */
 	public IMacroStateListener[] getMacroStateListeners() {
@@ -503,22 +529,31 @@ public class MacroManager {
 	}
 
 	/**
+	 * Provides the macro record context or null if the macro engine is not
+	 * recording.
+	 *
 	 * @return the macro record context created when macro record started or null if
-	 *         it's not currently recording.
+	 *         it is not currently recording.
 	 */
 	public IMacroRecordContext getMacroRecordContext() {
 		return fMacroRecordContext;
 	}
 
 	/**
+	 * Provides the macro playback context or null if the macro engine is not
+	 * playing back.
+	 *
 	 * @return the macro playback context created when macro playback started or
-	 *         null if it's not currently recording.
+	 *         null if it is not currently recording.
 	 */
 	public IMacroPlaybackContext getMacroPlaybackContext() {
 		return fMacroPlaybackContext;
 	}
 
 	/**
+	 * Provides the number of macro instructions in the macro being currently
+	 * recorded or -1 if there is no macro being recorded.
+	 *
 	 * @return the number of macro instructions in the macro currently recorded or
 	 *         -1 if no macro is being recorded.
 	 */
diff --git a/bundles/org.eclipse.e4.core.macros/src/org/eclipse/e4/core/macros/internal/MacroServiceImplementation.java b/bundles/org.eclipse.e4.core.macros/src/org/eclipse/e4/core/macros/internal/MacroServiceImplementation.java
index 7b71821f..d97eef95 100644
--- a/bundles/org.eclipse.e4.core.macros/src/org/eclipse/e4/core/macros/internal/MacroServiceImplementation.java
+++ b/bundles/org.eclipse.e4.core.macros/src/org/eclipse/e4/core/macros/internal/MacroServiceImplementation.java
@@ -68,8 +68,8 @@ public class MacroServiceImplementation implements EMacroService {
 	private MacroManager fMacroManager;
 
 	/**
-	 * A filter which allows blacklisting registered macro listeners. Note that it's
-	 * private and has no setters because it's meant only to be used in tests
+	 * A filter which allows blacklisting registered macro listeners. Note that it is
+	 * private and has no setters because it is meant only to be used in tests
 	 * (through reflection).
 	 */
 	private Predicate<IConfigurationElement> fFilterMacroListeners;
@@ -157,8 +157,11 @@ public class MacroServiceImplementation implements EMacroService {
 	}
 
 	/**
-	 * @return Returns the fMacroInstructionIdToFactory (creates it lazily if it
-	 *         still wasn't created).
+	 * Provides a map which maps macro instruction ids to the factory used to
+	 * recreate the related instruction.
+	 *
+	 * @return a map with macro instruction id to the related factory (creates it
+	 *         lazily if it still wasn't created).
 	 */
 	private Map<String, IMacroInstructionFactory> getMacroInstructionIdToFactory() {
 		if (fMacroInstructionIdToFactory == null) {
@@ -285,14 +288,11 @@ public class MacroServiceImplementation implements EMacroService {
 	 * A map which maps accepted command ids when recording a macro to whether they
 	 * should be recorded as a macro instruction to be played back later on.
 	 */
-	private Map<String, Boolean> fCustomizedCommandIds;
+	private Map<String, Boolean> fCommandIdToRecordFlag;
 
-	/**
-	 * @return a set with the commands that are accepted when macro recording.
-	 */
-	private Map<String, Boolean> getInternalcommandHandling() {
-		if (fCustomizedCommandIds == null) {
-			fCustomizedCommandIds = new HashMap<>();
+	private Map<String, Boolean> getCommandIdToRecordFlag() {
+		if (fCommandIdToRecordFlag == null) {
+			fCommandIdToRecordFlag = new HashMap<>();
 			for (IConfigurationElement ce : fExtensionRegistry
 					.getConfigurationElementsFor(MACRO_COMMAND_HANDLING_EXTENSION_POINT)) {
 				if (MACRO_COMMAND_HANDLING_ELEMENT.equals(ce.getName())
@@ -300,22 +300,22 @@ public class MacroServiceImplementation implements EMacroService {
 						&& ce.getAttribute(MACRO_COMMAND_HANDLING_RECORDING) != null) {
 					Boolean recordMacroInstruction = Boolean
 							.parseBoolean(ce.getAttribute(MACRO_COMMAND_HANDLING_RECORDING));
-					fCustomizedCommandIds.put(ce.getAttribute(MACRO_COMMAND_HANDLING_ID), recordMacroInstruction);
+					fCommandIdToRecordFlag.put(ce.getAttribute(MACRO_COMMAND_HANDLING_ID), recordMacroInstruction);
 				}
 			}
 		}
-		return fCustomizedCommandIds;
+		return fCommandIdToRecordFlag;
 	}
 
 	@Override
-	public boolean isCommandRecorded(String commandId) {
-		Map<String, Boolean> macrocommandHandling = getInternalcommandHandling();
+	public boolean getRecordCommandInMacro(String commandId) {
+		Map<String, Boolean> macrocommandHandling = getCommandIdToRecordFlag();
 		return macrocommandHandling.getOrDefault(commandId, true);
 	}
 
 	@Override
 	public void setRecordCommandInMacro(String commandId, boolean recordMacroInstruction) {
-		getInternalcommandHandling().put(commandId, recordMacroInstruction);
+		getCommandIdToRecordFlag().put(commandId, recordMacroInstruction);
 	}
 
 	@Override
diff --git a/bundles/org.eclipse.e4.core.macros/src/org/eclipse/e4/core/macros/internal/SavedJSMacro.java b/bundles/org.eclipse.e4.core.macros/src/org/eclipse/e4/core/macros/internal/SavedJSMacro.java
index 61ede841..24af1086 100644
--- a/bundles/org.eclipse.e4.core.macros/src/org/eclipse/e4/core/macros/internal/SavedJSMacro.java
+++ b/bundles/org.eclipse.e4.core.macros/src/org/eclipse/e4/core/macros/internal/SavedJSMacro.java
@@ -30,7 +30,7 @@ import org.eclipse.e4.core.macros.MacroPlaybackException;
 
 /**
  * Actually loads a macro from a JS file to be played back. Works with the
- * contents saved from {@link ComposableMacro#toJSBytes()}.
+ * contents saved from {@code ComposableMacro#toJSBytes()}.
  * <p>
  * Currently the saved macro is a JavaScript file to be played back again with a
  * "runMacro" function which may have multiple "runMacroInstruction" calls to
diff --git a/bundles/org.eclipse.e4.core.macros/src/org/eclipse/e4/core/macros/package-info.java b/bundles/org.eclipse.e4.core.macros/src/org/eclipse/e4/core/macros/package-info.java
index 09637daf..52a1127a 100644
--- a/bundles/org.eclipse.e4.core.macros/src/org/eclipse/e4/core/macros/package-info.java
+++ b/bundles/org.eclipse.e4.core.macros/src/org/eclipse/e4/core/macros/package-info.java
@@ -34,9 +34,9 @@ package org.eclipse.e4.core.macros;
  * </p>
  *
  * <p>
- * -- note that it's important that things are not the other way around: the
+ * -- note that it is important that things are not the other way around: the
  * macro plugin is a thin layer to start/stop macro recording and provide the
- * basic abstractions and management of macros, it's up to the clients to be
+ * basic abstractions and management of macros, it is up to the clients to be
  * aware that they are in macro record mode and act accordingly, issuing
  * commands to be recorded and later played back.
  * </p>
@@ -80,7 +80,7 @@ package org.eclipse.e4.core.macros;
  *
  * <p>
  * {@link org.eclipse.e4.core.macros.IMacroPlaybackContext}: received by a macro
- * instruction when it's being played back.
+ * instruction when it is being played back.
  * </p>
  *
  * <p>
@@ -106,7 +106,7 @@ package org.eclipse.e4.core.macros;
  * </p>
  *
  * <p>
- * -- Note: it's possible for the user to start a record mode and playback a
+ * -- Note: it is possible for the user to start a record mode and playback a
  * previous macro in such a mode (although the opposite is not true).
  * </p>
  *
@@ -239,10 +239,10 @@ package org.eclipse.e4.core.macros;
  * </p>
  *
  * <p>
- * Afterward, when it's time to play a macro instruction back, the contents of
+ * Afterward, when it is time to play a macro instruction back, the contents of
  * the map are gotten from disk and will be recreated through factories
  * registered in the org.eclipse.e4.core.macros.macroInstructionsFactory
- * extension point (so it's important to note that if a custom macro instruction
+ * extension point (so it is important to note that if a custom macro instruction
  * is created, a factory to recreate it must be registered).
  * </p>
  *
diff --git a/bundles/org.eclipse.e4.ui.macros/META-INF/MANIFEST.MF b/bundles/org.eclipse.e4.ui.macros/META-INF/MANIFEST.MF
index 0180cbe9..558263b9 100644
--- a/bundles/org.eclipse.e4.ui.macros/META-INF/MANIFEST.MF
+++ b/bundles/org.eclipse.e4.ui.macros/META-INF/MANIFEST.MF
@@ -24,7 +24,8 @@ Require-Bundle: org.eclipse.e4.ui.model.workbench;bundle-version="1.1",
  org.eclipse.ui.console,
  org.eclipse.e4.ui.bindings;bundle-version="0.11",
  org.eclipse.e4.core.services;bundle-version="2.0",
- org.eclipse.e4.core.commands
+ org.eclipse.e4.core.commands,
+ org.eclipse.e4.ui.services
 Bundle-RequiredExecutionEnvironment: JavaSE-1.8
 Import-Package: javax.inject,
  org.eclipse.core.runtime;version="3.5",
diff --git a/bundles/org.eclipse.e4.ui.macros/src/org/eclipse/e4/ui/macros/Activator.java b/bundles/org.eclipse.e4.ui.macros/src/org/eclipse/e4/ui/macros/Activator.java
index 9c7cc186..cf7d37b6 100644
--- a/bundles/org.eclipse.e4.ui.macros/src/org/eclipse/e4/ui/macros/Activator.java
+++ b/bundles/org.eclipse.e4.ui.macros/src/org/eclipse/e4/ui/macros/Activator.java
@@ -12,27 +12,42 @@ package org.eclipse.e4.ui.macros;
 
 import org.eclipse.core.runtime.IStatus;
 import org.eclipse.core.runtime.Status;
-import org.eclipse.jface.resource.ImageDescriptor;
 import org.eclipse.ui.plugin.AbstractUIPlugin;
 
-@SuppressWarnings("javadoc")
+/**
+ * Plug-in activator for the macros ui.
+ */
 public class Activator extends AbstractUIPlugin {
 
+	/**
+	 * Default plug-in activator instance.
+	 */
 	private static Activator plugin;
 
+	/**
+	 * Upon creating it, set it as the default instance in the class.
+	 */
 	public Activator() {
 		super();
 		plugin = this;
 	}
 
+	/**
+	 * Provides the default plug-in activator instance.
+	 *
+	 * @return the default plug-in activator instance.
+	 */
 	public static Activator getDefault() {
 		return plugin;
 	}
 
-	public static ImageDescriptor getImageDescriptor(String key) {
-		return getDefault().getImageRegistry().getDescriptor(key);
-	}
 
+	/**
+	 * Logs an exception.
+	 *
+	 * @param exception
+	 *            the exception to be logged.
+	 */
 	public static void log(Throwable exception) {
 		try {
 			if (plugin != null) {
diff --git a/bundles/org.eclipse.e4.ui.macros/src/org/eclipse/e4/ui/macros/internal/EditorUtils.java b/bundles/org.eclipse.e4.ui.macros/src/org/eclipse/e4/ui/macros/internal/EditorUtils.java
index 8a80cb98..8db68be1 100644
--- a/bundles/org.eclipse.e4.ui.macros/src/org/eclipse/e4/ui/macros/internal/EditorUtils.java
+++ b/bundles/org.eclipse.e4.ui.macros/src/org/eclipse/e4/ui/macros/internal/EditorUtils.java
@@ -38,20 +38,34 @@ public class EditorUtils {
 	private final static String TARGET_EDITOR_PART = "TARGET_EDITOR_PART"; //$NON-NLS-1$
 
 	/**
-	 * @return the StyledText related to the current editor or null if there's no
+	 * Provides the styled text which is active from the current editor or null if
+	 * it is not available.
+	 *
+	 * @return the StyledText related to the current editor or null if there is no
 	 *         such widget available (i.e.: if the current editor is not a text
-	 *         editor or if there's no open editor).
+	 *         editor or if there is no open editor).
 	 */
 	public static StyledText getActiveStyledText() {
 		IEditorPart activeEditor = getActiveEditorPart();
 		if (activeEditor == null) {
 			return null;
 		}
-		return getEditorPartStyledText(activeEditor);
+		Control control = activeEditor.getAdapter(Control.class);
+		StyledText styledText = null;
+		if (control instanceof StyledText) {
+			styledText = (StyledText) control;
+		}
+		return styledText;
 	}
 
+	/**
+	 * Provides a way to get the editor part which is currently active or null if
+	 * there's no current editor part.
+	 *
+	 * @return the active editor part.
+	 */
 	public static IEditorPart getActiveEditorPart() {
-		IWorkbenchWindow activeWorkbenchWindow = getActivateWorkbenchWindow();
+		IWorkbenchWindow activeWorkbenchWindow = getActiveWorkbenchWindow();
 		if (activeWorkbenchWindow == null) {
 			return null;
 		}
@@ -63,9 +77,11 @@ public class EditorUtils {
 	}
 
 	/**
-	 * @return the currently active workbench window or null if not available.
+	 * Provides the current active workbench window or null if it is not available.
+	 *
+	 * @return the current active workbench window or null if it is not available.
 	 */
-	public static IWorkbenchWindow getActivateWorkbenchWindow() {
+	public static IWorkbenchWindow getActiveWorkbenchWindow() {
 		IWorkbench workbench;
 		try {
 			workbench = PlatformUI.getWorkbench();
@@ -76,21 +92,6 @@ public class EditorUtils {
 	}
 
 	/**
-	 * @param editor
-	 *            the editor for which we want the StyledText.
-	 * @return the StyledText related to the current editor or null if it doesn't
-	 *         have a StyledText.
-	 */
-	public static StyledText getEditorPartStyledText(IEditorPart editor) {
-		Control control = editor.getAdapter(Control.class);
-		StyledText styledText = null;
-		if (control instanceof StyledText) {
-			styledText = (StyledText) control;
-		}
-		return styledText;
-	}
-
-	/**
 	 * Caches the current styled text as being the one active in the passed macro
 	 * context.
 	 *
diff --git a/bundles/org.eclipse.e4.ui.macros/src/org/eclipse/e4/ui/macros/internal/UserNotifications.java b/bundles/org.eclipse.e4.ui.macros/src/org/eclipse/e4/ui/macros/internal/UserNotifications.java
index 68bfa4cf..6d8a1c16 100644
--- a/bundles/org.eclipse.e4.ui.macros/src/org/eclipse/e4/ui/macros/internal/UserNotifications.java
+++ b/bundles/org.eclipse.e4.ui.macros/src/org/eclipse/e4/ui/macros/internal/UserNotifications.java
@@ -10,9 +10,12 @@
  *******************************************************************************/
 package org.eclipse.e4.ui.macros.internal;
 
+import javax.inject.Inject;
+import javax.inject.Named;
 import org.eclipse.core.runtime.IStatus;
 import org.eclipse.core.runtime.Status;
 import org.eclipse.e4.ui.macros.Activator;
+import org.eclipse.e4.ui.services.IServiceConstants;
 import org.eclipse.jface.action.IStatusLineManager;
 import org.eclipse.jface.dialogs.MessageDialog;
 import org.eclipse.jface.dialogs.MessageDialogWithToggle;
@@ -23,7 +26,6 @@ import org.eclipse.ui.IEditorPart;
 import org.eclipse.ui.IEditorSite;
 import org.eclipse.ui.IWorkbenchPage;
 import org.eclipse.ui.IWorkbenchWindow;
-import org.eclipse.ui.PlatformUI;
 
 /**
  * Helper class to show notifications to the user.
@@ -36,14 +38,18 @@ public class UserNotifications {
 
 	private static final String NO_EDITOR_ON_MACRO_RECORD_STARTUP_NOTIFICATION_MSG = "NO_EDITOR_ON_MACRO_RECORD_STARTUP_NOTIFICATION_MSG"; //$NON-NLS-1$
 
+	@Named(IServiceConstants.ACTIVE_SHELL)
+	@Inject
+	private Shell shell;
+
 	/**
 	 * Sets a given message to be shown to the user.
 	 *
 	 * @param message
 	 *            the message to be shown or null to clear it.
 	 */
-	public static void setMessage(String message) {
-		IStatusLineManager statusLineManager = UserNotifications.getStatusLineManager();
+	public void setMessage(String message) {
+		IStatusLineManager statusLineManager = getStatusLineManager();
 		if (statusLineManager != null) {
 			statusLineManager.setMessage(message);
 			if (message == null) {
@@ -59,7 +65,7 @@ public class UserNotifications {
 	 * @param message
 	 *            the error message to be shown (cannot be null).
 	 */
-	public static void showErrorMessage(String message) {
+	public void showErrorMessage(String message) {
 		Activator plugin = Activator.getDefault();
 		if (plugin != null) {
 			// Log it
@@ -67,13 +73,12 @@ public class UserNotifications {
 		}
 
 		// Make it visible to the user.
-		IStatusLineManager statusLineManager = UserNotifications.getStatusLineManager();
+		IStatusLineManager statusLineManager = getStatusLineManager();
 		if (statusLineManager == null) {
-			Shell parent = UserNotifications.getParent();
-			if (parent == null) {
+			if (shell == null) {
 				System.err.println(Messages.Activator_ErrorMacroRecording + ": " + message); //$NON-NLS-1$
 			} else {
-				MessageDialog.openWarning(parent, Messages.Activator_ErrorMacroRecording, message);
+				MessageDialog.openWarning(shell, Messages.Activator_ErrorMacroRecording, message);
 			}
 		} else {
 			statusLineManager.setErrorMessage(message);
@@ -86,21 +91,13 @@ public class UserNotifications {
 	}
 
 	/**
-	 * @return a shell to be used as a dialog's parent.
-	 */
-	private static Shell getParent() {
-		IWorkbenchWindow activeWorkbenchWindow = PlatformUI.getWorkbench().getActiveWorkbenchWindow();
-		if (activeWorkbenchWindow == null) {
-			return null;
-		}
-		return activeWorkbenchWindow.getShell();
-	}
-
-	/**
+	 * Provides the status line manager to be used for notifications or null if it
+	 * is not available.
+	 *
 	 * @return the available status line manager for the current editor.
 	 */
-	private static IStatusLineManager getStatusLineManager() {
-		IWorkbenchWindow activeWorkbenchWindow = EditorUtils.getActivateWorkbenchWindow();
+	private IStatusLineManager getStatusLineManager() {
+		IWorkbenchWindow activeWorkbenchWindow = EditorUtils.getActiveWorkbenchWindow();
 		if (activeWorkbenchWindow == null) {
 			return null;
 		}
@@ -122,7 +119,7 @@ public class UserNotifications {
 	/**
 	 * Show a notification regarding limitations on find/replace.
 	 */
-	public static void notifyFindReplace() {
+	public void notifyFindReplace() {
 		openWarningWithIgnoreToggle(Messages.UserNotifications_FindReplaceDialogTitle,
 				Messages.UserNotifications_FindReplaceDialogMessage, FIND_REPLACE_USER_NOTIFICATION_MSG);
 	}
@@ -130,7 +127,7 @@ public class UserNotifications {
 	/**
 	 * Show a notification regarding limitations on the editor changing.
 	 */
-	public static void notifyCurrentEditor() {
+	public void notifyCurrentEditor() {
 		openWarningWithIgnoreToggle(Messages.UserNotifications_EditorChangedTitle,
 				Messages.UserNotifications_EditorChangedMessage, CURRENT_EDITOR_NOTIFICATION_MSG);
 	}
@@ -139,7 +136,7 @@ public class UserNotifications {
 	 * Show a notification regarding not having an editor opened when record
 	 * started.
 	 */
-	public static void notifyNoEditorOnMacroRecordStartup() {
+	public void notifyNoEditorOnMacroRecordStartup() {
 		openWarningWithIgnoreToggle(Messages.UserNotifications_NoEditorForRecordTitle,
 				Messages.UserNotifications_NoEditorForRecordMsg, NO_EDITOR_ON_MACRO_RECORD_STARTUP_NOTIFICATION_MSG);
 	}
@@ -148,17 +145,16 @@ public class UserNotifications {
 	 * Show a notification regarding not having an editor opened when playback
 	 * started.
 	 */
-	public static void notifyNoEditorOnMacroPlaybackStartup() {
+	public void notifyNoEditorOnMacroPlaybackStartup() {
 		openWarningWithIgnoreToggle(Messages.UserNotifications_NoEditorForPlaybackTitle,
 				Messages.UserNotifications_NoEditorForPlaybackMsg, NO_EDITOR_ON_MACRO_RECORD_STARTUP_NOTIFICATION_MSG);
 	}
 
-	private static void openWarningWithIgnoreToggle(String title, String message, String key) {
-		IWorkbenchWindow activateWorkbenchWindow = EditorUtils.getActivateWorkbenchWindow();
-		if (activateWorkbenchWindow == null) {
+	private void openWarningWithIgnoreToggle(String title, String message, String key) {
+		if (shell == null) {
+			System.err.println(message);
 			return;
 		}
-		Shell shell = activateWorkbenchWindow.getShell();
 
 		IPreferenceStore store = Activator.getDefault().getPreferenceStore();
 		String val = store.getString(key);
diff --git a/bundles/org.eclipse.e4.ui.macros/src/org/eclipse/e4/ui/macros/internal/actions/KeepMacroUIUpdated.java b/bundles/org.eclipse.e4.ui.macros/src/org/eclipse/e4/ui/macros/internal/actions/KeepMacroUIUpdated.java
index 4f9d5bd4..2d43cd1c 100644
--- a/bundles/org.eclipse.e4.ui.macros/src/org/eclipse/e4/ui/macros/internal/actions/KeepMacroUIUpdated.java
+++ b/bundles/org.eclipse.e4.ui.macros/src/org/eclipse/e4/ui/macros/internal/actions/KeepMacroUIUpdated.java
@@ -10,6 +10,9 @@
  *******************************************************************************/
 package org.eclipse.e4.ui.macros.internal.actions;
 
+import javax.inject.Inject;
+import org.eclipse.e4.core.contexts.ContextInjectionFactory;
+import org.eclipse.e4.core.contexts.IEclipseContext;
 import org.eclipse.e4.core.macros.EMacroService;
 import org.eclipse.e4.core.macros.IMacroInstruction;
 import org.eclipse.e4.core.macros.IMacroInstructionsListener;
@@ -19,7 +22,7 @@ import org.eclipse.ui.PlatformUI;
 import org.eclipse.ui.commands.ICommandService;
 
 /**
- * Make sure that the toolbar elements are kept properly updated even if the
+ * Makes sure that the toolbar elements are kept properly updated even if the
  * macro is programmatically stopped.
  */
 public class KeepMacroUIUpdated implements IMacroStateListener {
@@ -30,17 +33,43 @@ public class KeepMacroUIUpdated implements IMacroStateListener {
 	 */
 	private static final class MacroInstructionsListener implements IMacroInstructionsListener {
 
+		/**
+		 * Helper class for giving notifications to the user.
+		 */
+		private UserNotifications fUserNotifications;
+
+		/**
+		 * @param userNotifications
+		 *            the helper class for giving notifications to the user.
+		 */
+		public MacroInstructionsListener(UserNotifications userNotifications) {
+			this.fUserNotifications = userNotifications;
+		}
+
 		@Override
 		public void postAddMacroInstruction(IMacroInstruction macroInstruction) {
-			UserNotifications.setMessage(Messages.KeepMacroUIUpdated_RecordedInMacro + macroInstruction);
+			this.fUserNotifications.setMessage(Messages.KeepMacroUIUpdated_RecordedInMacro + macroInstruction);
 		}
 	}
 
-	boolean wasRecording = false;
+	private boolean wasRecording = false;
+
+	private boolean wasPlayingBack = false;
 
-	boolean wasPlayingBack = false;
+	private IMacroInstructionsListener fMacroInstructionsListener;
 
-	IMacroInstructionsListener fMacroInstructionsListener;
+	private UserNotifications fUserNotifications;
+
+	@Inject
+	private IEclipseContext fEclipseContext;
+
+	private UserNotifications getUserNotifications() {
+		if (fUserNotifications == null) {
+			fUserNotifications = new UserNotifications();
+			ContextInjectionFactory.inject(fUserNotifications, fEclipseContext);
+		}
+		return fUserNotifications;
+	}
 
 	@Override
 	public void macroStateChanged(EMacroService macroService, StateChange stateChange) {
@@ -51,26 +80,26 @@ public class KeepMacroUIUpdated implements IMacroStateListener {
 		// Show a message to the user saying about the macro state.
 		if (macroService.isRecording() != wasRecording) {
 			if (!wasRecording) {
-				UserNotifications.setMessage(Messages.KeepMacroUIUpdated_StartMacroRecord);
+				getUserNotifications().setMessage(Messages.KeepMacroUIUpdated_StartMacroRecord);
 			} else {
 				// When we stop the record, clear the message.
-				UserNotifications.setMessage(null);
+				getUserNotifications().setMessage(null);
 			}
 			wasRecording = macroService.isRecording();
 		}
 		if (macroService.isPlayingBack() != wasPlayingBack) {
 			if (!wasPlayingBack) {
-				UserNotifications.setMessage(Messages.KeepMacroUIUpdated_StartMacroPlayback);
+				getUserNotifications().setMessage(Messages.KeepMacroUIUpdated_StartMacroPlayback);
 			} else {
 				// When we stop the playback, clear the message.
-				UserNotifications.setMessage(null);
+				getUserNotifications().setMessage(null);
 			}
 			wasPlayingBack = macroService.isPlayingBack();
 		}
 
 		if (macroService.isRecording()) {
 			if (fMacroInstructionsListener == null) {
-				fMacroInstructionsListener = new MacroInstructionsListener();
+				fMacroInstructionsListener = new MacroInstructionsListener(getUserNotifications());
 				macroService.addMacroInstructionsListener(fMacroInstructionsListener);
 			}
 		} else {
diff --git a/bundles/org.eclipse.e4.ui.macros/src/org/eclipse/e4/ui/macros/internal/actions/Messages.java b/bundles/org.eclipse.e4.ui.macros/src/org/eclipse/e4/ui/macros/internal/actions/Messages.java
index 74df0820..bcfc886d 100644
--- a/bundles/org.eclipse.e4.ui.macros/src/org/eclipse/e4/ui/macros/internal/actions/Messages.java
+++ b/bundles/org.eclipse.e4.ui.macros/src/org/eclipse/e4/ui/macros/internal/actions/Messages.java
@@ -13,15 +13,21 @@ package org.eclipse.e4.ui.macros.internal.actions;
 import org.eclipse.osgi.util.NLS;
 
 /**
- *
+ * Helper class to get NLSed messages.
  */
 @SuppressWarnings("javadoc")
 public class Messages extends NLS {
+
 	private static final String BUNDLE_NAME = "org.eclipse.e4.ui.macros.internal.actions.messages"; //$NON-NLS-1$
+
 	public static String KeepMacroUIUpdated_RecordedInMacro;
+
 	public static String KeepMacroUIUpdated_StartMacroRecord;
+
 	public static String KeepMacroUIUpdated_StartMacroPlayback;
+
 	public static String MacroPlaybackAction_ErrorRunningMacro;
+
 	static {
 		// initialize resource bundle
 		NLS.initializeMessages(BUNDLE_NAME, Messages.class);
diff --git a/bundles/org.eclipse.e4.ui.macros/src/org/eclipse/e4/ui/macros/internal/actions/ToggleMacroRecordAction.java b/bundles/org.eclipse.e4.ui.macros/src/org/eclipse/e4/ui/macros/internal/actions/ToggleMacroRecordAction.java
index 9cecffb1..207c8988 100644
--- a/bundles/org.eclipse.e4.ui.macros/src/org/eclipse/e4/ui/macros/internal/actions/ToggleMacroRecordAction.java
+++ b/bundles/org.eclipse.e4.ui.macros/src/org/eclipse/e4/ui/macros/internal/actions/ToggleMacroRecordAction.java
@@ -34,6 +34,7 @@ public class ToggleMacroRecordAction extends AbstractHandler implements IElement
 		return null;
 	}
 
+	@SuppressWarnings("rawtypes")
 	@Override
 	public void updateElement(UIElement element, Map parameters) {
 		element.setChecked(PlatformUI.getWorkbench().getService(EMacroService.class).isRecording());
diff --git a/bundles/org.eclipse.e4.ui.macros/src/org/eclipse/e4/ui/macros/internal/keybindings/CommandManagerExecutionListener.java b/bundles/org.eclipse.e4.ui.macros/src/org/eclipse/e4/ui/macros/internal/keybindings/CommandManagerExecutionListener.java
index 8442a50e..78b8b7c5 100644
--- a/bundles/org.eclipse.e4.ui.macros/src/org/eclipse/e4/ui/macros/internal/keybindings/CommandManagerExecutionListener.java
+++ b/bundles/org.eclipse.e4.ui.macros/src/org/eclipse/e4/ui/macros/internal/keybindings/CommandManagerExecutionListener.java
@@ -17,6 +17,8 @@ import org.eclipse.core.commands.IExecutionListener;
 import org.eclipse.core.commands.NotHandledException;
 import org.eclipse.core.commands.ParameterizedCommand;
 import org.eclipse.e4.core.commands.EHandlerService;
+import org.eclipse.e4.core.contexts.ContextInjectionFactory;
+import org.eclipse.e4.core.contexts.IEclipseContext;
 import org.eclipse.e4.core.macros.EMacroService;
 import org.eclipse.e4.ui.macros.Activator;
 import org.eclipse.e4.ui.macros.internal.EditorUtils;
@@ -61,14 +63,23 @@ public class CommandManagerExecutionListener implements IExecutionListener {
 	private final EHandlerService fHandlerService;
 
 	/**
+	 * The Eclipse context for dependency injection.
+	 */
+	private IEclipseContext fEclipseContext;
+
+	/**
 	 * @param macroService
 	 *            the macro service
 	 * @param handlerService
 	 *            the handler service (used to execute actions).
+	 * @param eclipseContext
+	 *            Eclipse context for dependency injection.
 	 */
-	public CommandManagerExecutionListener(EMacroService macroService, EHandlerService handlerService) {
+	public CommandManagerExecutionListener(EMacroService macroService, EHandlerService handlerService,
+			IEclipseContext eclipseContext) {
 		this.fMacroService = macroService;
 		this.fHandlerService = handlerService;
+		this.fEclipseContext = eclipseContext;
 	}
 
 	@Override
@@ -113,7 +124,7 @@ public class CommandManagerExecutionListener implements IExecutionListener {
 		}
 		if (fMacroService.isRecording()) {
 			// Record it if needed.
-			if (fMacroService.isCommandRecorded(commandId)) {
+			if (fMacroService.getRecordCommandInMacro(commandId)) {
 				if (commandAndTrigger.trigger instanceof Event) {
 					Event swtEvent = (Event) commandAndTrigger.trigger;
 					// Only record commands executed in the initial editor.
@@ -135,11 +146,17 @@ public class CommandManagerExecutionListener implements IExecutionListener {
 		if (acceptEvent(event)) {
 			if ("org.eclipse.ui.edit.findReplace".equals(commandId)) { //$NON-NLS-1$
 				// We can't deal with find/replace at this point. Let the user know.
-				UserNotifications.notifyFindReplace();
+				UserNotifications userNotifications = new UserNotifications();
+				ContextInjectionFactory.inject(userNotifications, fEclipseContext);
+				try {
+					userNotifications.notifyFindReplace();
+				} finally {
+					ContextInjectionFactory.uninject(userNotifications, fEclipseContext);
+				}
 			}
 		}
 		// Let's check if it should actually be recorded.
-		if (fMacroService.isCommandRecorded(commandId)) {
+		if (fMacroService.getRecordCommandInMacro(commandId)) {
 			if (!acceptEvent(event)) {
 				fParameterizedCommandsAndTriggerStack.add(null);
 				return;
@@ -157,8 +174,15 @@ public class CommandManagerExecutionListener implements IExecutionListener {
 	public static interface IFilter {
 
 		/**
+		 * If the given event should have a macro instruction created to it,
+		 * {@code true} should be returned and if no macro instruction should be created
+		 * from the filter, {@code false} should be returned.
+		 *
 		 * @param swtEvent
-		 * @return true if the given swtEvent should be accepted.
+		 *            the event to be filtered.
+		 *
+		 * @return {@code true} if the given swtEvent should be accepted and
+		 *         {@code false} otherwise.
 		 */
 		boolean acceptEvent(Event swtEvent);
 	}
@@ -173,7 +197,7 @@ public class CommandManagerExecutionListener implements IExecutionListener {
 	}
 
 	/**
-	 * Note that it's private and shouldn't be usually changed, although the current
+	 * Note that it is private and shouldn't be usually changed, although the current
 	 * structure is helpful as it allows us to accept any event on tests through
 	 * reflection.
 	 */
diff --git a/bundles/org.eclipse.e4.ui.macros/src/org/eclipse/e4/ui/macros/internal/keybindings/CommandManagerExecutionListenerInstaller.java b/bundles/org.eclipse.e4.ui.macros/src/org/eclipse/e4/ui/macros/internal/keybindings/CommandManagerExecutionListenerInstaller.java
index fa4356fc..f655e577 100644
--- a/bundles/org.eclipse.e4.ui.macros/src/org/eclipse/e4/ui/macros/internal/keybindings/CommandManagerExecutionListenerInstaller.java
+++ b/bundles/org.eclipse.e4.ui.macros/src/org/eclipse/e4/ui/macros/internal/keybindings/CommandManagerExecutionListenerInstaller.java
@@ -13,6 +13,7 @@ package org.eclipse.e4.ui.macros.internal.keybindings;
 import javax.inject.Inject;
 import org.eclipse.core.commands.CommandManager;
 import org.eclipse.e4.core.commands.EHandlerService;
+import org.eclipse.e4.core.contexts.IEclipseContext;
 import org.eclipse.e4.core.macros.EMacroService;
 import org.eclipse.e4.core.macros.IMacroPlaybackContext;
 import org.eclipse.e4.core.macros.IMacroRecordContext;
@@ -31,8 +32,16 @@ public class CommandManagerExecutionListenerInstaller implements IMacroStateList
 	@Inject
 	private EHandlerService fHandlerService;
 
+	@Inject
+	private IEclipseContext fEclipseContext;
+
 	private CommandManagerExecutionListener fCommandManagerExecutionListener;
 
+	/**
+	 * Gets the command manager execution listener.
+	 *
+	 * @return the command manager execution listener.
+	 */
 	public CommandManagerExecutionListener getCommandManagerExecutionListener() {
 		return fCommandManagerExecutionListener;
 	}
@@ -41,7 +50,8 @@ public class CommandManagerExecutionListenerInstaller implements IMacroStateList
 	public void macroStateChanged(EMacroService macroService, StateChange stateChange) {
 		if (macroService.isRecording()) {
 			if (fCommandManagerExecutionListener == null) {
-				fCommandManagerExecutionListener = new CommandManagerExecutionListener(macroService, fHandlerService);
+				fCommandManagerExecutionListener = new CommandManagerExecutionListener(macroService, fHandlerService,
+						fEclipseContext);
 				fCommandManager.addExecutionListener(fCommandManagerExecutionListener);
 			}
 		} else {
diff --git a/bundles/org.eclipse.e4.ui.macros/src/org/eclipse/e4/ui/macros/internal/keybindings/MacroInstructionForParameterizedCommand.java b/bundles/org.eclipse.e4.ui.macros/src/org/eclipse/e4/ui/macros/internal/keybindings/MacroInstructionForParameterizedCommand.java
index 1cc0213c..b382db6d 100644
--- a/bundles/org.eclipse.e4.ui.macros/src/org/eclipse/e4/ui/macros/internal/keybindings/MacroInstructionForParameterizedCommand.java
+++ b/bundles/org.eclipse.e4.ui.macros/src/org/eclipse/e4/ui/macros/internal/keybindings/MacroInstructionForParameterizedCommand.java
@@ -53,6 +53,12 @@ public class MacroInstructionForParameterizedCommand implements IMacroInstructio
 
 	private Event fEvent;
 
+	/**
+	 * @param cmd
+	 *            the command recorded.
+	 * @param handlerService
+	 *            the service to be used to execute the command.
+	 */
 	public MacroInstructionForParameterizedCommand(ParameterizedCommand cmd, EHandlerService handlerService) {
 		this.fCmd = cmd;
 		this.fHandlerService = handlerService;
@@ -63,12 +69,12 @@ public class MacroInstructionForParameterizedCommand implements IMacroInstructio
 	 *            the command recorded.
 	 * @param event
 	 *            the related event.
-	 * @param keybindingDispatcher
-	 *            the dispatcher to be used to execute commands.
+	 * @param handlerService
+	 *            the service to be used to execute the command.
 	 */
 	public MacroInstructionForParameterizedCommand(ParameterizedCommand cmd, Event event,
-			EHandlerService keybindingDispatcher) {
-		this(cmd, keybindingDispatcher);
+			EHandlerService handlerService) {
+		this(cmd, handlerService);
 
 		// Create a new event (we want to make sure that only the given info is
 		// really needed on playback and don't want to keep a reference to the
@@ -172,6 +178,9 @@ public class MacroInstructionForParameterizedCommand implements IMacroInstructio
 	}
 
 	/**
+	 * Deserializes a macro instruction which was created from a parameterized
+	 * command.
+	 *
 	 * @param map
 	 *            a map (created from {@link #toMap()}.
 	 * @param commandManager
diff --git a/bundles/org.eclipse.e4.ui.macros/src/org/eclipse/e4/ui/macros/internal/keybindings/Messages.java b/bundles/org.eclipse.e4.ui.macros/src/org/eclipse/e4/ui/macros/internal/keybindings/Messages.java
index 0c3c5b87..bc351515 100644
--- a/bundles/org.eclipse.e4.ui.macros/src/org/eclipse/e4/ui/macros/internal/keybindings/Messages.java
+++ b/bundles/org.eclipse.e4.ui.macros/src/org/eclipse/e4/ui/macros/internal/keybindings/Messages.java
@@ -12,8 +12,12 @@ package org.eclipse.e4.ui.macros.internal.keybindings;
 
 import org.eclipse.osgi.util.NLS;
 
+/**
+ * Helper class to get NLSed messages.
+ */
 @SuppressWarnings("javadoc")
 public class Messages extends NLS {
+
 	private static final String BUNDLE_NAME = "org.eclipse.e4.ui.macros.internal.keybindings.messages"; //$NON-NLS-1$
 
 	public static String CommandManagerExecutionListener_CommandNotRecorded;
diff --git a/bundles/org.eclipse.ui.workbench.texteditor.macros/src/org/eclipse/ui/workbench/texteditor/macros/internal/AbstractSWTEventMacroInstruction.java b/bundles/org.eclipse.ui.workbench.texteditor.macros/src/org/eclipse/ui/workbench/texteditor/macros/internal/AbstractSWTEventMacroInstruction.java
index b9f89a23..b37e3cfd 100644
--- a/bundles/org.eclipse.ui.workbench.texteditor.macros/src/org/eclipse/ui/workbench/texteditor/macros/internal/AbstractSWTEventMacroInstruction.java
+++ b/bundles/org.eclipse.ui.workbench.texteditor.macros/src/org/eclipse/ui/workbench/texteditor/macros/internal/AbstractSWTEventMacroInstruction.java
@@ -55,6 +55,8 @@ public abstract class AbstractSWTEventMacroInstruction implements IMacroInstruct
 	}
 
 	/**
+	 * Provides the event type of the events that this macro instruction is related
+	 * to.
 	 *
 	 * @return the event type of the events that this macro instruction is related
 	 *         to.
diff --git a/bundles/org.eclipse.ui.workbench.texteditor.macros/src/org/eclipse/ui/workbench/texteditor/macros/internal/EditorPartMacroInstaller.java b/bundles/org.eclipse.ui.workbench.texteditor.macros/src/org/eclipse/ui/workbench/texteditor/macros/internal/EditorPartMacroInstaller.java
index 885d5899..17ddb4fd 100644
--- a/bundles/org.eclipse.ui.workbench.texteditor.macros/src/org/eclipse/ui/workbench/texteditor/macros/internal/EditorPartMacroInstaller.java
+++ b/bundles/org.eclipse.ui.workbench.texteditor.macros/src/org/eclipse/ui/workbench/texteditor/macros/internal/EditorPartMacroInstaller.java
@@ -10,6 +10,8 @@
  *******************************************************************************/
 package org.eclipse.ui.workbench.texteditor.macros.internal;
 
+import javax.inject.Inject;
+import org.eclipse.e4.core.contexts.IEclipseContext;
 import org.eclipse.e4.core.macros.CancelMacroException;
 import org.eclipse.e4.core.macros.EMacroService;
 import org.eclipse.e4.core.macros.IMacroRecordContext;
@@ -23,13 +25,16 @@ public class EditorPartMacroInstaller implements IMacroStateListener {
 
 	private static final String NOTIFY_MACRO_ONLY_IN_CURRENT_EDITOR = "NOTIFY_MACRO_ONLY_IN_CURRENT_EDITOR"; //$NON-NLS-1$
 
+	@Inject
+	private IEclipseContext fEclipseContext;
+
 	@Override
 	public void macroStateChanged(EMacroService macroService, StateChange stateChange)
 			throws CancelMacroException {
 		if (stateChange == StateChange.RECORD_STARTED) {
 			IMacroRecordContext context = macroService.getMacroRecordContext();
 			NotifyMacroOnlyInCurrentEditor notifyMacroOnlyInCurrentEditor = new NotifyMacroOnlyInCurrentEditor(
-					macroService);
+					macroService, fEclipseContext);
 			notifyMacroOnlyInCurrentEditor.checkEditorActiveForMacroRecording();
 
 			notifyMacroOnlyInCurrentEditor.install();
@@ -43,7 +48,7 @@ public class EditorPartMacroInstaller implements IMacroStateListener {
 				notifyMacroOnlyInCurrentEditor.uninstall();
 			}
 		} else if (stateChange == StateChange.PLAYBACK_STARTED) {
-			new NotifyMacroOnlyInCurrentEditor(macroService).checkEditorActiveForMacroPlayback();
+			new NotifyMacroOnlyInCurrentEditor(macroService, fEclipseContext).checkEditorActiveForMacroPlayback();
 		}
 	}
 }
diff --git a/bundles/org.eclipse.ui.workbench.texteditor.macros/src/org/eclipse/ui/workbench/texteditor/macros/internal/NotifyMacroOnlyInCurrentEditor.java b/bundles/org.eclipse.ui.workbench.texteditor.macros/src/org/eclipse/ui/workbench/texteditor/macros/internal/NotifyMacroOnlyInCurrentEditor.java
index 0feba10e..b11f96a9 100644
--- a/bundles/org.eclipse.ui.workbench.texteditor.macros/src/org/eclipse/ui/workbench/texteditor/macros/internal/NotifyMacroOnlyInCurrentEditor.java
+++ b/bundles/org.eclipse.ui.workbench.texteditor.macros/src/org/eclipse/ui/workbench/texteditor/macros/internal/NotifyMacroOnlyInCurrentEditor.java
@@ -10,6 +10,8 @@
  *******************************************************************************/
 package org.eclipse.ui.workbench.texteditor.macros.internal;
 
+import org.eclipse.e4.core.contexts.ContextInjectionFactory;
+import org.eclipse.e4.core.contexts.IEclipseContext;
 import org.eclipse.e4.core.macros.CancelMacroPlaybackException;
 import org.eclipse.e4.core.macros.CancelMacroRecordingException;
 import org.eclipse.e4.core.macros.EMacroService;
@@ -112,12 +114,32 @@ public class NotifyMacroOnlyInCurrentEditor {
 	 */
 	private StyledText fLastEditor;
 
+	private UserNotifications fUserNotifications;
+
+	private IEclipseContext fEclipseContext;
+
 	/**
 	 * @param macroService
 	 *            the macro service.
+	 * @param eclipseContext
+	 *            eclipse context for dependency injection.
 	 */
-	public NotifyMacroOnlyInCurrentEditor(EMacroService macroService) {
-		this.fMacroService = macroService;
+	public NotifyMacroOnlyInCurrentEditor(EMacroService macroService, IEclipseContext eclipseContext) {
+		fMacroService = macroService;
+		fEclipseContext = eclipseContext;
+	}
+
+	/**
+	 * Provides the class which should be used to give user notifications.
+	 *
+	 * @return the helper class for giving user notifications.
+	 */
+	public UserNotifications getUserNotifications() {
+		if (fUserNotifications == null) {
+			fUserNotifications = new UserNotifications();
+			ContextInjectionFactory.inject(fUserNotifications, fEclipseContext);
+		}
+		return fUserNotifications;
 	}
 
 	/**
@@ -130,11 +152,11 @@ public class NotifyMacroOnlyInCurrentEditor {
 			StyledText currentStyledText = EditorUtils.getActiveStyledText();
 			StyledText targetStyledText = EditorUtils.getTargetStyledText(macroRecordContext);
 			if (targetStyledText != currentStyledText && currentStyledText != fLastEditor) {
-				UserNotifications.setMessage(Messages.NotifyMacroOnlyInCurrentEditor_NotRecording);
-				UserNotifications.notifyCurrentEditor();
+				getUserNotifications().setMessage(Messages.NotifyMacroOnlyInCurrentEditor_NotRecording);
+				getUserNotifications().notifyCurrentEditor();
 			} else if (targetStyledText == currentStyledText && fLastEditor != null
 					&& fLastEditor != currentStyledText) {
-				UserNotifications.setMessage(Messages.NotifyMacroOnlyInCurrentEditor_Recording);
+				getUserNotifications().setMessage(Messages.NotifyMacroOnlyInCurrentEditor_Recording);
 			}
 			fLastEditor = currentStyledText;
 		}
@@ -142,14 +164,14 @@ public class NotifyMacroOnlyInCurrentEditor {
 
 	/**
 	 * Check if there's some active editor when the macro recording starts.
-	 * 
+	 *
 	 * @throws CancelMacroRecordingException
 	 */
 	public void checkEditorActiveForMacroRecording() throws CancelMacroRecordingException {
 		StyledText currentStyledText = EditorUtils.getActiveStyledText();
 		if (currentStyledText == null) {
-			UserNotifications.setMessage(Messages.NotifyMacroOnlyInCurrentEditor_NotRecording);
-			UserNotifications.notifyNoEditorOnMacroRecordStartup();
+			getUserNotifications().setMessage(Messages.NotifyMacroOnlyInCurrentEditor_NotRecording);
+			getUserNotifications().notifyNoEditorOnMacroRecordStartup();
 			throw new CancelMacroRecordingException();
 		}
 	}
@@ -162,7 +184,7 @@ public class NotifyMacroOnlyInCurrentEditor {
 	public void checkEditorActiveForMacroPlayback() throws CancelMacroPlaybackException {
 		StyledText currentStyledText = EditorUtils.getActiveStyledText();
 		if (currentStyledText == null) {
-			UserNotifications.notifyNoEditorOnMacroPlaybackStartup();
+			getUserNotifications().notifyNoEditorOnMacroPlaybackStartup();
 			throw new CancelMacroPlaybackException();
 		}
 	}
diff --git a/bundles/org.eclipse.ui.workbench.texteditor.macros/src/org/eclipse/ui/workbench/texteditor/macros/internal/StyledTextKeyDownMacroInstruction.java b/bundles/org.eclipse.ui.workbench.texteditor.macros/src/org/eclipse/ui/workbench/texteditor/macros/internal/StyledTextKeyDownMacroInstruction.java
index d95d7b98..1f666ad4 100644
--- a/bundles/org.eclipse.ui.workbench.texteditor.macros/src/org/eclipse/ui/workbench/texteditor/macros/internal/StyledTextKeyDownMacroInstruction.java
+++ b/bundles/org.eclipse.ui.workbench.texteditor.macros/src/org/eclipse/ui/workbench/texteditor/macros/internal/StyledTextKeyDownMacroInstruction.java
@@ -65,11 +65,6 @@ import org.eclipse.swt.widgets.Event;
 		return new StyledTextKeyDownMacroInstruction(event);
 	}
 
-	/*
-	 * (non-Javadoc)
-	 *
-	 * @see java.lang.Object#toString()
-	 */
 	@Override
 	public String toString() {
 		return Messages.StyledTextKeyDownMacroInstruction_KeyDown
diff --git a/bundles/org.eclipse.ui.workbench.texteditor.macros/src/org/eclipse/ui/workbench/texteditor/macros/internal/StyledTextKeyDownMacroInstructionFactory.java b/bundles/org.eclipse.ui.workbench.texteditor.macros/src/org/eclipse/ui/workbench/texteditor/macros/internal/StyledTextKeyDownMacroInstructionFactory.java
index 64d8f8cf..7bc61df6 100644
--- a/bundles/org.eclipse.ui.workbench.texteditor.macros/src/org/eclipse/ui/workbench/texteditor/macros/internal/StyledTextKeyDownMacroInstructionFactory.java
+++ b/bundles/org.eclipse.ui.workbench.texteditor.macros/src/org/eclipse/ui/workbench/texteditor/macros/internal/StyledTextKeyDownMacroInstructionFactory.java
@@ -15,6 +15,7 @@ import org.eclipse.e4.core.macros.IMacroInstruction;
 import org.eclipse.e4.core.macros.IMacroInstructionFactory;
 
 /**
+ * A factory which will create macro instructions for styled text key presses.
  */
 public class StyledTextKeyDownMacroInstructionFactory implements IMacroInstructionFactory {
 
diff --git a/bundles/org.eclipse.ui.workbench.texteditor.macros/src/org/eclipse/ui/workbench/texteditor/macros/internal/StyledTextMacroRecorder.java b/bundles/org.eclipse.ui.workbench.texteditor.macros/src/org/eclipse/ui/workbench/texteditor/macros/internal/StyledTextMacroRecorder.java
index 8f3684ba..7dcf2003 100644
--- a/bundles/org.eclipse.ui.workbench.texteditor.macros/src/org/eclipse/ui/workbench/texteditor/macros/internal/StyledTextMacroRecorder.java
+++ b/bundles/org.eclipse.ui.workbench.texteditor.macros/src/org/eclipse/ui/workbench/texteditor/macros/internal/StyledTextMacroRecorder.java
@@ -24,6 +24,10 @@ public class StyledTextMacroRecorder implements Listener {
 
 	private final EMacroService fMacroService;
 
+	/**
+	 * @param macroService
+	 *            the macro service where macro instructions should be added.
+	 */
 	public StyledTextMacroRecorder(EMacroService macroService) {
 		this.fMacroService = macroService;
 	}
@@ -40,10 +44,27 @@ public class StyledTextMacroRecorder implements Listener {
 		}
 	}
 
+	/**
+	 * Uninstalls the macro recorder from the given styled text (which means that it
+	 * will no longer create macro instructions from key presses in the given styled
+	 * text).
+	 *
+	 * @param textWidget
+	 *            the styled text where key presses were previously being listened
+	 *            to.
+	 */
 	public void uninstall(StyledText textWidget) {
 		textWidget.removeListener(SWT.KeyDown, this);
 	}
 
+	/**
+	 * Starts listening to key presses in the given styled text so that macro
+	 * instructions are created and added to the macro service when macro record is
+	 * active.
+	 *
+	 * @param textWidget
+	 *            the styled text to be listened for key presses.
+	 */
 	public void install(StyledText textWidget) {
 		textWidget.addListener(SWT.KeyDown, this);
 	}