TestSupport: target_cmd_*: Add some doc comments

Signed-off-by: Konrad Rzeszutek Wilk <konrad.wilk@oracle.com>
Signed-off-by: Ian Jackson <Ian.Jackson@eu.citrix.com>

diff --git a/Osstest/TestSupport.pm b/Osstest/TestSupport.pm
index c36dc76cc627aa8052ba1ade61f16a12c1e5af40..f54962aa87bea619ded8750f03256f8842a7d4dc 100644 (file)
--- a/Osstest/TestSupport.pm
+++ b/Osstest/TestSupport.pm
@@ -692,8 +692,18 @@ sub tcmd { # $tcmd will be put between '' but not escaped
            'ssh', sshopts(), @{ $extrasshopts || [] },
            sshuho($user,$ho), $tcmd);
 }
+
+# target_cmd[_VARIANT]($ho, $cmd, [ $timeout, \@EXTRASSHOPTS ]);
+#
+# target_cmd executes $cmd with the shell as the osstest user on $ho.
+# stdout goes to our own stdout.  dies if the command exits nonzero.
 sub target_cmd ($$;$$) { tcmd(undef,undef,0, 'osstest',@_); }
+
+# Like target_cmd but as root.
 sub target_cmd_root ($$;$$) { tcmd(undef,undef,0, 'root',@_); }
+
+# Like target_cmd_root, but does not die if the command fails.
+# Instead, returns the wait status (ie, what came in $?)
 sub target_cmd_root_status ($$;$$) { tcmd(undef,undef,1, 'root',@_); }
 
 sub tcmdout {
@@ -708,6 +718,7 @@ sub tcmdout {
     return $r;
 }
 
+# Like target_cmd[_root], but collect the stdout and return it as a string.
 sub target_cmd_output ($$;$) { tcmdout('osstest',@_); }
 sub target_cmd_output_root ($$;$) { tcmdout('root',@_); }