From 13114e972bf1b8ac752fca01d7eeb967ff6ec4fb Mon Sep 17 00:00:00 2001
From: Darren Schroeder <343840+fdncred@users.noreply.github.com>
Date: Sat, 19 Aug 2023 08:23:11 -0500
Subject: [PATCH] try to document the more obscure testbin commands (#10057)

# Description

This PR tries to document some of the more obscure testbin parameters
and what they do. I still don't grok all of them.

# User-Facing Changes
<!-- List of all changes that impact the user experience here. This
helps us keep track of breaking changes. -->

# Tests + Formatting
<!--
Don't forget to add tests that cover your changes.

Make sure you've run and fixed any issues with these commands:

- `cargo fmt --all -- --check` to check standard code formatting (`cargo
fmt --all` applies these changes)
- `cargo clippy --workspace -- -D warnings -D clippy::unwrap_used -A
clippy::needless_collect -A clippy::result_large_err` to check that
you're using the standard code style
- `cargo test --workspace` to check that all tests pass
- `cargo run -- -c "use std testing; testing run-tests --path
crates/nu-std"` to run the tests for the standard library

> **Note**
> from `nushell` you can also use the `toolkit` as follows
> ```bash
> use toolkit.nu # or use an `env_change` hook to activate it
automatically
> toolkit check pr
> ```
-->

# After Submitting
<!-- If your PR had any user-facing changes, update [the
documentation](https://github.com/nushell/nushell.github.io) after the
PR is merged, if necessary. This will help us keep the docs up to date.
-->
---
 src/test_bins.rs | 22 +++++++++++++++++-----
 1 file changed, 17 insertions(+), 5 deletions(-)

diff --git a/src/test_bins.rs b/src/test_bins.rs
index 52f995a7f7..93a5b809eb 100644
--- a/src/test_bins.rs
+++ b/src/test_bins.rs
@@ -1,12 +1,10 @@
-use std::io::{self, BufRead, Read, Write};
-
 use nu_command::hook::{eval_env_change_hook, eval_hook};
 use nu_engine::eval_block;
 use nu_parser::parse;
 use nu_protocol::engine::{EngineState, Stack, StateWorkingSet};
 use nu_protocol::{CliError, PipelineData, Value};
 use nu_std::load_standard_library;
-// use nu_test_support::fs::in_directory;
+use std::io::{self, BufRead, Read, Write};
 
 /// Echo's value of env keys from args
 /// Example: nu --testbin env_echo FOO BAR
@@ -24,6 +22,9 @@ pub fn echo_env(to_stdout: bool) {
     }
 }
 
+/// Cross platform echo using println!()
+/// Example: nu --testbin echo a b c
+/// a b c
 pub fn cococo() {
     let args: Vec<String> = args();
 
@@ -37,6 +38,7 @@ pub fn cococo() {
     }
 }
 
+/// Cross platform cat (open a file, print the contents) using read_to_string and println!()
 pub fn meow() {
     let args: Vec<String> = args();
 
@@ -46,7 +48,7 @@ pub fn meow() {
     }
 }
 
-// A binary version of meow
+/// Cross platform cat (open a file, print the contents) using read() and write_all() / binary
 pub fn meowb() {
     let args: Vec<String> = args();
 
@@ -65,10 +67,18 @@ pub fn relay() {
         .expect("failed to copy stdin to stdout");
 }
 
+/// Cross platform echo but concats arguments without space and NO newline
+/// nu --testbin nonu a b c
+/// abc
 pub fn nonu() {
     args().iter().skip(1).for_each(|arg| print!("{arg}"));
 }
 
+/// Repeat a string or char N times
+/// nu --testbin repeater a 5
+/// aaaaa
+/// nu --testbin repeater test 5
+/// testtesttesttesttest
 pub fn repeater() {
     let mut stdout = io::stdout();
     let args = args();
@@ -84,7 +94,7 @@ pub fn repeater() {
     let _ = stdout.flush();
 }
 
-// A version of repeater that can output binary data, even null bytes
+/// A version of repeater that can output binary data, even null bytes
 pub fn repeat_bytes() {
     let mut stdout = io::stdout();
     let args = args();
@@ -110,6 +120,7 @@ pub fn repeat_bytes() {
     let _ = stdout.flush();
 }
 
+/// Another type of echo that outputs a parameter per line, looping infinitely
 pub fn iecho() {
     // println! panics if stdout gets closed, whereas writeln gives us an error
     let mut stdout = io::stdout();
@@ -124,6 +135,7 @@ pub fn fail() {
     std::process::exit(1);
 }
 
+/// With no parameters, will chop a character off the end of each line
 pub fn chop() {
     if did_chop_arguments() {
         // we are done and don't care about standard input.