Document the fluent-syntax bin files

fluent-syntax/src/bin/parser.rs

@@ -1,3 +1,19 @@
+//! This is a simple CLI utility to take in an FTL file and output the AST.
+//!
+//! ## View the `Debug` representation:
+//!
+//! From the root directory of the `fluent-rs` repo:
+//!
+//! ```sh
+//! cargo run --bin parser -- ./fluent-syntax/tests/fixtures/literal_expressions.ftl
+//! ```
+//!
+//! ## View the `json` representation:
+//!
+//! ```sh
+//! cargo run --bin parser --features json -- ./fluent-syntax/tests/fixtures/literal_expressions.ftl
+//! ```
+
 use fluent_syntax::parser::parse;
 use std::env;
 use std::fs::File;
@@ -13,7 +29,8 @@ fn read_file(path: &str) -> Result<String, io::Error> {
 
 fn main() {
     let args: Vec<String> = env::args().collect();
-    let source = read_file(args.get(1).expect("Pass an argument")).expect("Failed to fetch file");
+    let source = read_file(args.get(1).expect("Pass a file path as the first argument"))
+        .expect("Failed to fetch file");
 
     let (ast, errors) = match parse(source.as_str()) {
         Ok(ast) => (ast, None),

fluent-syntax/src/bin/update_fixtures.rs

@@ -1,3 +1,11 @@
+//! Run the `update_fixtures` binary after updating any of the `benches` `.ftl` fixtures.
+//! This will update the `.json` files used in reference tests.
+//!
+//! This file must be run from `{PROJECT_ROOT}/fluent-syntax`
+//!
+//! ```sh
+//! cargo run --bin update_fixtures --features="json"
+//! ```
 use std::fs;
 use std::io;
 
@@ -17,7 +25,9 @@ fn main() {
 
     for sample in samples {
         let path = format!("./benches/{}.ftl", sample);
-        let source = read_file(&path).unwrap();
+        let source = read_file(&path).expect(
+            "Could not read the benches file. Are you running this from the correct directory? It must be run from `{PROJECT_ROOT}/fluent-syntax`",
+        );
         let ast = parse(source).unwrap();
         let target_json = serde_json::to_string_pretty(&ast).unwrap();
         let new_path = format!("./tests/fixtures/benches/{}.json", sample);