Merged FILE-FOLDER-API (5.2.0) to HEAD (5.2)

119711 jvonka: FileFolder API - consistently handle node aspects &/or properties  (on create or update)
   - also allow specialise node type (when updating a node)
   - minor tweaks to javadoc/comments
   - RA-635, RA-636, RA-639


git-svn-id: https://svn.alfresco.com/repos/alfresco-enterprise/alfresco/HEAD/root@126360 c4b6b30b-aa2e-2d43-bbcb-ca4b014f7261

source/java/org/alfresco/rest/api/nodes/NodeChildrenRelation.java

@@ -35,7 +35,11 @@ import java.util.ArrayList;
 import java.util.List;
 
 /**
- * TODO ... work-in-progress
+ * Node Children
+ *
+ * - list folder children
+ * - create folder &/or empty file
+ * - create (ie. upload) file with content
  * 
  * @author janv
  * @author Jamal Kaabi-Mofrad
@@ -59,17 +63,12 @@ public class NodeChildrenRelation implements RelationshipResourceAction.Read<Nod
 
     /**
      * List folder children - returns a filtered/sorted/paged list of nodes that are immediate children of the parent folder
-     * 
-     * TODO filtering, sorting, ...
-     * TODO metadata/properties & permissions etc ...
-     * 
-     * @param parentFolderNodeId String id of parent folder - will also accept aliases "-root-" (Company Home) or "-my-" (current user's home folder)
+     *
+     * @param parentFolderNodeId String id of parent folder - will also accept well-known alias, eg. -root- or -my- or -shared-
      * 
      * Optional query parameters:
-     * 
-     * - incFiles
-     * - incFolders
-     * 
+     *
+     * - select
      * - properties
      * - where
      * - orderBy
@@ -90,7 +89,7 @@ public class NodeChildrenRelation implements RelationshipResourceAction.Read<Nod
     /**
      * Create one or more nodes (folder or empty file) below parent folder.
      *
-     * Note: for parent folder nodeId, can also use well-known alias, eg. -root- or -my-
+     * Note: for parent folder nodeId, can also use well-known alias, eg. -root- or -my- or -shared-
      *
      * If parentFolderNodeId does not exist, EntityNotFoundException (status 404).
      * If parentFolderNodeId does not represent a folder, InvalidArgumentException (status 400).