Update documentation examples to remove potential panics

[simonsso]

Use map inside Option to avoid unwraps which would panic before assert! is even called.

[simonsso]

The same pattern was used on other places in the same file. By comparing Some("value") the assert would actually check with None too.

[epage]

unwrap is another form of assert and showing that its None doesn't really buy us much. On the other hand, this makes the example code noisier. I'm leaning towards not merging this but would be open to further clarification on why you felt this was important.

[simonsso]

unwrap in example code (1) teaches new developers bad habits (2) the assert_eq! is not executed on the None case so the test is redundant and misleading to the reader of the code (3) the same pattern was already present in the same file - if this makes the documentation noisier it should also be reverted to the unwrap style to keep consistency.

Lets assume one of the tests should be failing, the error messages from new version comparing the Option<> would be

thread 'main' panicked at clap_builder/src/builder/arg.rs:19:1:
assertion `left == right` failed
  left: None
 right: Some("/home/clap")
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace

But for the unwrap there are two different points where it could fail

Failure one:

Test executable failed (exit status: 101).

stderr:
thread 'main' panicked at clap_builder/src/builder/arg.rs:19:44:
called `Option::unwrap()` on a `None` value
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace

Failure two:

Test executable failed (exit status: 101).

stderr:
thread 'main' panicked at clap_builder/src/builder/arg.rs:19:1:
assertion `left == right` failed
  left: "/home/clap"
 right: "/home/clapX"
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace

I think the modified version is better starting point for library user who copies the example code and want to use it as a base for proper error handling.

[epage]

unwrap in example code (1) teaches new developers bad habits

Its an assert which is test code and not error handling

(2) the assert_eq! is not executed on the None case so the test is redundant and misleading to the reader of the code

This doesn't make sense to me. unwraps are an assert of their own.

(3) the same pattern was already present in the same file

That doesn't say which way to change it though.

Considering that, I'm going to go ahead and close this for now.