Update insert specification

2 files changed, 17 insertions, 15 deletions

diff --git a/lib/modifiers/summary/insertArticle.js b/lib/modifiers/summary/insertArticle.js
index d97943e..0a010b4 100644
--- a/lib/modifiers/summary/insertArticle.js
+++ b/lib/modifiers/summary/insertArticle.js
@@ -4,10 +4,11 @@ var editArticle = require('./editArticle');
 var indexArticleLevels = require('./indexArticleLevels');
 
 /**
-    Insert an article in a summary at a specific position
+    Returns a new Summary with the article at the given level, with
+    subsequent article shifted.
 
     @param {Summary} summary
-    @param {String|Article} level: level to insert after
+    @param {String|Article} level: level to insert at
     @param {Article} article
     @return {Summary}
 */
diff --git a/lib/modifiers/summary/moveArticle.js b/lib/modifiers/summary/moveArticle.js
index 83904ec..9819245 100644
--- a/lib/modifiers/summary/moveArticle.js
+++ b/lib/modifiers/summary/moveArticle.js
@@ -3,29 +3,30 @@ var removeArticle = require('./removeArticle');
 var insertArticle = require('./insertArticle');
 
 /**
-    Remove an article from a level, and insert it after another.
+    Returns a new summary, with the given article removed from its
+    origin level, and placed at the given target level.
 
     @param {Summary} summary
-    @param {String|SummaryArticle} from: level to remove
-    @param {String|SummaryArticle} to: level to insert after
+    @param {String|SummaryArticle} origin: level to remove
+    @param {String|SummaryArticle} target: the level where the article will be found
     @return {Summary}
 */
-function moveArticle(summary, from, to) {
+function moveArticle(summary, origin, target) {
     // Coerce to level
-    var fromLevel = is.string(from)? from : from.getLevel();
-    var toLevel = is.string(to)? to : to.getLevel();
+    var originLevel = is.string(origin)? origin : origin.getLevel();
+    var targetLevel = is.string(target)? target : target.getLevel();
 
-    var article = summary.getByLevel(fromLevel);
+    var article = summary.getByLevel(originLevel);
 
     // Remove
-    var removed = removeArticle(summary, from);
+    var removed = removeArticle(summary, origin);
 
-    // Adjust toLevel if removing impacted it
-    toLevel = arrayToLevel(
-        shiftLevel(levelToArray(fromLevel),
-                   levelToArray(toLevel)));
+    // Adjust targetLevel if removing impacted it
+    targetLevel = arrayToLevel(
+        shiftLevel(levelToArray(originLevel),
+                   levelToArray(targetLevel)));
     // Re-insert
-    return insertArticle(removed, to, article);
+    return insertArticle(removed, target, article);
 }
 
 /**