Tidied up command documentation

Author: dantleech

CHANGELOG.md

@@ -8,6 +8,8 @@ dev-master
 
 - [DoctrinePhpcrBundle] Shell must now be initiated in a different way in
   embedded mode. The DoctrinePhpcrBundle will need to be updated.
+- [node:shared:remove] Removed this command and integrated it into
+  `node:remove` instead (`node:remove . --shared`)
 
 ### Bug fixes
 

src/PHPCR/Shell/Console/Command/Phpcr/AccessControlPrivilegeListCommand.php

@@ -31,12 +31,7 @@ protected function configure()
 List the privileges of the current session or the node at the given path.
 
 List the privileges for the object specified by <info>abs-path</info>
-argument. If <info>abs-path</info>
-is the absolute path of an accessible node then the specified object is
-that node. If <info>abs-path</info> is null then the specified object is the
-repository as a whole and the privileges in question are those that are
-not associated with any particular node. This includes such privileges
-as being able administer the node type registry, for example.
+argument.
 
 By default the returned privileges are those for which
 AccessControlManagerInterface::hasPrivileges() would return true.

src/PHPCR/Shell/Console/Command/Phpcr/LockUnlockCommand.php

@@ -30,15 +30,6 @@ protected function configure()
 node. As well, the corresponding lock token is removed from the set of
 lock tokens held by the current Session.
 
-If the node does not currently hold a lock or holds a lock for which
-this Session is not the owner and is not a "lock-superuser", then a
-\PHPCR\Lock\LockException is thrown.
-
-<b>Note:</b>
-However that the system may give permission to a non-owning session
-to unlock a lock. Typically such "lock-superuser" capability is intended
-to facilitate administrational clean-up of orphaned open-scoped locks.
-
 Note that it is possible to unlock a node even if it is checked-in (the
 lock-related properties will be changed despite the checked-in status).
 HERE

src/PHPCR/Shell/Console/Command/Phpcr/NodeCloneCommand.php

@@ -21,7 +21,7 @@ class NodeCloneCommand extends BasePhpcrCommand
     protected function configure()
     {
         $this->setName('node:clone');
-        $this->setDescription('Clone a node');
+        $this->setDescription('Clone a node (immediate)');
         $this->addArgument('srcPath', InputArgument::REQUIRED, 'Path to source node');
         $this->addArgument('destPath', InputArgument::REQUIRED, 'Path to destination node');
         $this->addArgument('srcWorkspace', InputArgument::OPTIONAL, 'If specified, copy from this workspace');
@@ -31,15 +31,9 @@ protected function configure()
 <info>srcWorkspace</info> to the new location at <info>destAbsPath</info> in
 the current workspace.
 
-Unlike the signature of copy that copies between workspaces, this method does
-not assign new identifiers to the newly cloned nodes but preserves the
-identifiers of their respective source nodes. This applies to both
-referenceable and non-referenceable nodes.
-
-In some implementations there may be cases where preservation of a
-non-referenceable identifier is not possible, due to how non-referenceable
-identifiers are constructed in that implementation. In such a case this method
-will throw a RepositoryException.
+This method does not assign new identifiers to the newly cloned nodes but
+preserves the identifiers of their respective source nodes. This applies to
+both referenceable and non-referenceable nodes.
 
 If the <info>--remove-existing</info> option is set and an existing node in
 this workspace (the destination workspace) has the same identifier as a node

src/PHPCR/Shell/Console/Command/Phpcr/NodeCopyCommand.php

@@ -20,7 +20,7 @@ class NodeCopyCommand extends BasePhpcrCommand
     protected function configure()
     {
         $this->setName('node:copy');
-        $this->setDescription('Copy a node');
+        $this->setDescription('Copy a node (immediate)');
         $this->addArgument('srcPath', InputArgument::REQUIRED, 'Path to source node');
         $this->addArgument('destPath', InputArgument::REQUIRED, 'Path to destination node');
         $this->addArgument('srcWorkspace', InputArgument::OPTIONAL, 'If specified, copy from this workspace');
@@ -33,61 +33,6 @@ protected function configure()
 
 This is a workspace-write operation and therefore dispatches changes
 immediately and does not require a save.
-
-When a node N is copied to a path location where no node currently
-exists, a new node N' is created at that location.
-The subgraph rooted at and including N' (call it S') is created and is
-identical to the subgraph rooted at and including N (call it S) with the
-following exceptions:
-- Every node in S' is given a new and distinct identifier
-  - or, if <info>srcWorkspace</info> is given -
-  Every referenceable node in S' is given a new and distinct identifier
-  while every non-referenceable node in S' may be given a new and
-  distinct identifier.
-- The repository may automatically drop any mixin node type T present on
-  any node M in S. Dropping a mixin node type in this context means that
-  while M remains unchanged, its copy M' will lack the mixin T and any
-  child nodes and properties defined by T that are present on M. For
-  example, a node M that is mix:versionable may be copied such that the
-  resulting node M' will be a copy of N except that M' will not be
-  mix:versionable and will not have any of the properties defined by
-  mix:versionable. In order for a mixin node type to be dropped it must
-  be listed by name in the jcr:mixinTypes property of M. The resulting
-  jcr:mixinTypes property of M' will reflect any change.
-- If a node M in S is referenceable and its mix:referenceable mixin is
-  not dropped on copy, then the resulting jcr:uuid property of M' will
-  reflect the new identifier assigned to M'.
-- Each REFERENCE or WEAKEREFERENCE property R in S is copied to its new
-  location R' in S'. If R references a node M within S then the value of
-  R' will be the identifier of M', the new copy of M, thus preserving the
-  reference within the subgraph.
-
-When a node N is copied to a location where a node N' already exists, the
-repository may either immediately throw an ItemExistsException or attempt
-to update the node N' by selectively replacing part of its subgraph with
-a copy of the relevant part of the subgraph of N. If the node types of N
-and N' are compatible, the implementation supports update-on-copy for
-these node types and no other errors occur, then the copy will succeed.
-Otherwise an ItemExistsException is thrown.
-
-Which node types can be updated on copy and the details of any such
-updates are implementation-dependent. For example, some implementations
-may support update-on-copy for mix:versionable nodes. In such a case the
-versioning-related properties of the target node would remain unchanged
-(jcr:uuid, jcr:versionHistory, etc.) while the substantive content part
-of the subgraph would be replaced with that of the source node.
-
-The <info>destAbsPath</info> provided must not have an index on its final element. If
-it does then a RepositoryException is thrown. Strictly speaking, the
-<info>destAbsPath</info> parameter is actually an absolute path to the parent node of
-the new location, appended with the new name desired for the copied node.
-It does not specify a position within the child node ordering. If ordering
-is supported by the node type of the parent node of the new location, then
-the new copy of the node is appended to the end of the child node list.
-
-This method cannot be used to copy an individual property by itself. It
-copies an entire node and its subgraph (including, of course, any
-properties contained therein).
 HERE
         );
     }

src/PHPCR/Shell/Console/Command/Phpcr/NodeCreateCommand.php

@@ -35,13 +35,10 @@ protected function configure()
 If ordering is supported by the node type of the parent node of the new
 node then the new node is appended to the end of the child node list.
 
-If <info>primaryNodeTypeName</info> is specified, this type will be used (or a
-ConstraintViolationException thrown if this child type is not allowed).
+If <info>primaryNodeTypeName</info> is specified, this type will be used.
+
 Otherwise the new node's primary node type will be determined by the
-child node definitions in the node types of its parent. This may occur
-either immediately, on dispatch (save, whether within or without
-transactions) or on persist (save without transactions, commit within
-a transaction), depending on the implementation.
+child node definitions in the node types of its parent.
 HERE
         );
     }

src/PHPCR/Shell/Console/Command/Phpcr/NodeMixinAddCommand.php

@@ -30,21 +30,6 @@ protected function configure()
 added mixin or due to its primary type, through inheritance) then this
 method has no effect. Otherwise <info>mixinName</info> is added to this node's
 jcr:mixinTypes property.
-
-Semantically, the new node type may take effect immediately, on dispatch
-or on persist. The behavior is adopted must be the same as the behavior
-adopted for NodeInterface::setPrimaryType() and the behavior that
-occurs when a node is first created.
-
-A ConstraintViolationException is thrown either immediately or on save
-if a conflict with another assigned mixin or the primary node type
-occurs or for an implementation-specific reason. Implementations may
-differ on when this validation is done.
-
-In some implementations it may only be possible to add mixin types
-before a a node is persisted for the first time. In such cases any
-later calls to <info>addMixin</info> will throw a ConstraintViolationException
-either immediately, on dispatch or on persist.
 HERE
         );
     }

src/PHPCR/Shell/Console/Command/Phpcr/NodeMoveCommand.php

@@ -30,30 +30,6 @@ protected function configure()
 
 This is a session-write command and therefor requires a save to dispatch
 the change.
-
-The identifiers of referenceable nodes must not be changed by a move.
-The identifiers of non-referenceable nodes may change.
-
-A ConstraintViolationException is thrown either immediately, on dispatch
-or on persist, if performing this operation would violate a node type or
-implementation-specific constraint. Implementations may differ on when
-this validation is performed.
-
-As well, a ConstraintViolationException will be thrown on persist if an
-attempt is made to separately save either the source or destination
-node.
-
-Note that this behaviour differs from that of workspace::move
-, which is a workspace-write command and therefore immediately dispatches
-changes.
-
-The <info>destPath</info> provided must not have an index on its final element. If
-ordering is supported by the node type of the parent node of the new
-location, then the newly moved node is appended to the end of the child
-node list.
-
-This command cannot be used to move an individual property by itself. It
-moves an entire node and its subgraph.
 HERE
         );
     }

src/PHPCR/Shell/Console/Command/Phpcr/NodeOrderBeforeCommand.php

@@ -25,22 +25,15 @@ protected function configure()
         $this->addArgument('srcChildRelPath', InputArgument::REQUIRED, 'The relative path to the child node to be moved in the ordering');
         $this->addArgument('destChildRelPath', InputArgument::REQUIRED, 'The relative path to the child before which the node srcChildRelPath will be placed');
         $this->setHelp(<<<HERE
-If this node supports child node ordering, this method inserts the child
-node at <info>srcChildRelPath</info> into the child node list at the position
-immediately before <info>destChildRelPath</info>
+This command is used to change the order of a child node relative to the current node.
 
-To place the node <info>srcChildRelPath</info> at the end of the list, a
-destChildRelPath of null is used.
+For example, given that the node <path>/foobar</path> has the children <node>child2</node> and
+<node>child4</node> then:
 
-Note that (apart from the case where <info>destChildRelPath</info> is null) both of
-these arguments must be relative paths of depth one, in other words they
-are the names of the child nodes, possibly suffixed with an index.
+    PHPCRSH> cd foobar
+    PHPCRSH> node-order . child4 child2
 
-If <info>srcChildRelPath</info> and <info>destChildRelPath</info> are the same, then no change is
-made.
-
-This is session-write method, meaning that a change made by this method
-is dispatched on save.
+Will reorder "child4" before "child2".
 HERE
         );
     }

src/PHPCR/Shell/Console/Command/Phpcr/NodePropertyRemoveCommand.php

@@ -24,7 +24,7 @@ protected function configure()
         $this->setDescription('Remove the property at the given absolute path');
         $this->addArgument('absPath', InputArgument::REQUIRED, 'Absolute path to property');
         $this->setHelp(<<<HERE
-Remove the property from the current session at the given absolute path
+Remove the property from the current session at the given path
 HERE
         );
     }