more feedback

Author: sunshowers

code/organizing-binary/src/main.rs code/organizing-binary/src/bin/my-app.rscode/organizing-binary/src/main.rs renamed to code/organizing-binary/src/bin/my-app.rs

@@ -5,11 +5,13 @@ use clap::Parser;
 #[derive(Debug, Parser)]
 pub struct MyApp {
     // Options, subcommands etc
+    #[clap(short, long, default_value_t)]
+    my_arg: usize,
 }
 
 impl MyApp {
     pub fn exec(self) -> color_eyre::Result<()> {
-        // execute the command and return a result
-        unimplemented!()
+        println!("The value of my-arg is {}", self.my_arg);
+        Ok(())
     }
 }

code/organizing-binary/src/command.rs

@@ -2,9 +2,9 @@
 
 Thanks to the following reviewers who read through drafts of this document and provided invaluable feedback:
 
-- Manish Goregaokar ([Twitter](https://twitter.com/ManishEarth), [GitHub](https://github.com/Manishearth))
 - Ana Hobden ([Twitter](https://twitter.com/a_hoverbear), [GitHub](https://github.com/hoverbear))
+- Ed Page ([GitHub](https://github.com/epage))
+- Inanna Malick ([Twitter](https://twitter.com/inanna_malick/), [GitHub](https://github.com/inanna-malick))
 - jam1garner ([Twitter](https://twitter.com/jam1garner), [GitHub](https://github.com/jam1garner))
 - Jane Lusby ([Twitter](https://twitter.com/yaahc_), [GitHub](https://github.com/yaahc))
-- Inanna Malick ([Twitter](https://twitter.com/inanna_malick/), [GitHub](https://github.com/inanna-malick))
-- Ed Page ([GitHub](https://github.com/epage))
+- Manish Goregaokar ([Twitter](https://twitter.com/ManishEarth), [GitHub](https://github.com/Manishearth))

src/acknowledgments.md

@@ -41,6 +41,8 @@ Terminals use the same escape codes to support both colors and styles---bold, it
 
 **Applications *must not* use blinking text.** Blinking text can be distracting or difficult to read for many people. The HTML `<blink>` tag, which had similar behavior, was [removed from web pages](https://www.fastcompany.com/3015408/saying-goodbye-to-the-html-tag) around 2013.
 
+> TODO: add information about ASCII and Unicode symbols (including emoji) that are safe to use in terminals.
+
 ## ANSI color codes and Windows color APIs
 
 Most Unix terminals support [ANSI color codes](https://en.wikipedia.org/wiki/ANSI_escape_code#Colors). For example, turning the foreground color to "green" involves writing the characters `\x1b` (ESC), `[`, `32` (for green), and `m` to the terminal.

src/colors.md

@@ -46,9 +46,9 @@ Exactly how deep merges should go is application-specific.
 
 There are two main Rust libraries for managing hierarchical configuration:
 
-* [config](https://crates.io/crates/config). I've used this and it seems to work well.
-* [figment](https://crates.io/crates/figment). This seems quite nice as well, though I haven't used it.
+* [config](https://crates.io/crates/config). I've used this for my own projects.
+* [figment](https://crates.io/crates/figment). Seems high quality, though I haven't used it.
 
-These configuration libraries can be used in combination with serde, so that you can manage hierarchies and merges with dynamically typed variables at the edges of your program, then switch over to well-typed serde structures for the rest of your code. For how to do this with config, [see this example].
+These configuration libraries can be used in combination with serde, so that you can manage hierarchies and merges with dynamically typed variables at the edges of your program, then switch over to well-typed serde structures for validating the config's schema. For how to do this with config, [see this example].
 
 [see this example]: https://github.com/mehcode/config-rs/blob/53e43fbcf96b5c2a661d052a6e3d55fc3709f1e1/examples/hierarchical-env/settings.rs

src/hierarchical-config.md

@@ -14,21 +14,22 @@ Within a binary crate, here's the organization that's *recommended*.
 {{#rustdoc_include ../code/organizing-binary/src/lib.rs}}
 ```
 
-`my-app/src/main.rs`:
+`my-app/src/bin/my-app.rs`:
 ```rust
-{{#rustdoc_include ../code/organizing-binary/src/main.rs}}
+{{#rustdoc_include ../code/organizing-binary/src/bin/my-app.rs}}
 ```
 
 Notes:
 * **Most of the logic is within `command.rs`.**
   * In general, you *should* keep lib.rs as minimal as possible, unless your entire library fits in it. That's
     because all methods and fields in `lib.rs` are visible to the entire library---code in the top-level module
     cannot be marked private to the rest of the module.
-* **There's a `lib.rs` separate from the `main.rs`.**
-  * This is because `rustdoc` doesn't use standard privacy rules if building documentation from `main.rs`,
-  so private modules are visible in the public documentation.
+* **There's a `lib.rs` separate from the `my-app.rs` that contains `main`.**
+  * There are several advantages to having a `lib.rs`. In particular, `rustdoc` doesn't use standard privacy rules if building documentation from `main.rs`, so private modules are visible in the public documentation.
 * **Only the top-level `MyApp` is exported.**
   * The top-level `MyApp` is all `main.rs` should generally need to care about.
 * **`MyApp` is marked `#[doc(hidden)]`.**
   * The details of `MyApp` are only meant to be seen by `main`. The library is not part of the public API. Only
   the command-line interface is.
+* **`src/bin/my-app.rs` instead of `src/main.rs`.**
+  * While `src/main.rs` works just as well, `src/bin` makes it harder to accidentally import library code with `mod` statements.

src/organizing-binary.md

@@ -14,4 +14,4 @@ A binary crate *should* define its public API as consisting of the command-line
 * Mark old commands or arguments deprecated, and possibly hide them from help text. Continue to preserve their behavior.
 * If the program persists data on disk, make it possible to do forward transitions but not backward ones. Add a *format version* to persisted data and increment it every time the data format changes. If an old version of the program reads a format version it does not understand, error out gracefully.
 
-> Tip: You can use the [baptiste0928/cargo-install](https://github.com/baptiste0928/cargo-install) Cargo action to install a binary from crates.io, caching it if possible. This action lets you specify a version range, which plays well with the above binary versioning policy.
+> Tip: If you're using GitHub Actions for CI, use the [baptiste0928/cargo-install](https://github.com/baptiste0928/cargo-install) action to install a binary from crates.io, using a cached version if possible. This action lets you specify a version range, which plays well with the binary versioning policy above.