From 75d056f198e78c009035a461055c1d96e76d69d5 Mon Sep 17 00:00:00 2001
From: Derek Hulley <derek.hulley@alfresco.com>
Date: Fri, 4 Nov 2016 11:45:54 +0000
Subject: [PATCH] MNT-16527: Improve API documentation description for
 deleteNode, purgeArchivedNode and NodeService

git-svn-id: https://svn.alfresco.com/repos/alfresco-enterprise/alfresco/BRANCHES/DEV/5.2.N/root@132393 c4b6b30b-aa2e-2d43-bbcb-ca4b014f7261
---
 .../repo/node/archive/NodeArchiveService.java | 20 ++++++++++++++++---
 1 file changed, 17 insertions(+), 3 deletions(-)

diff --git a/source/java/org/alfresco/repo/node/archive/NodeArchiveService.java b/source/java/org/alfresco/repo/node/archive/NodeArchiveService.java
index 1274f68a0b..884ae4f3e5 100644
--- a/source/java/org/alfresco/repo/node/archive/NodeArchiveService.java
+++ b/source/java/org/alfresco/repo/node/archive/NodeArchiveService.java
@@ -26,16 +26,28 @@
 package org.alfresco.repo.node.archive;
 
 import java.util.List;
-
+
 import org.alfresco.query.PagingResults;
 import org.alfresco.service.cmr.repository.NodeRef;
+import org.alfresco.service.cmr.repository.NodeService;
 import org.alfresco.service.cmr.repository.StoreRef;
 import org.alfresco.service.namespace.NamespaceService;
 import org.alfresco.service.namespace.QName;
 
 /**
  * A service interface providing methods that map onto the low-level
- * node restore functionality.
+ * node restore functionality.
+ * <p>
+ * Node stores <i>may</i> be mapped to an associated archive node store.  For example, Alfresco ships with the mapping<br>
+ * {@link StoreRef#STORE_REF_WORKSPACE_SPACESSTORE workspace://SpacesStore} .. maps to .. {@link StoreRef#STORE_REF_ARCHIVE_SPACESSTORE archive://SpacesStore}.<br>
+ * When a node is {@link NodeService#deleteNode(NodeRef) deleted} from a regular workspace, it is moved to an archive store if there is a mapping.
+ * <p>
+ * This service operates <b>only on nodes that have been archived</b> by either
+ * <ul>
+ *   <li>{@link #getArchivedNode(NodeRef) retrieving archived nodes},</li>
+ *   <li>{@link #purgeArchivedNode(NodeRef) permanently deleting archived nodes},</li>
+ *   <li>or {@link #restoreArchivedNode(NodeRef) restoring archived nodes back to their original location}.</li>
+ * </ul>
  * 
  * @author Derek Hulley
  */
@@ -132,7 +144,9 @@ public interface NodeArchiveService
     /**
      * Permanently delete the archived node.
      * 
-     * @param archivedNodeRef the archived node to delete.
+     * @param archivedNodeRef the archived node to delete.
+     * 
+     * @see NodeService#deleteNode(NodeRef)
      */
     public void purgeArchivedNode(NodeRef archivedNodeRef);