From 1c286d7cdcc27c393568f6182dbb46d2eafd8df5 Mon Sep 17 00:00:00 2001
From: Brendan <2bndy5@gmail.com>
Date: Mon, 15 Jun 2026 02:42:21 -0700
Subject: [PATCH] docs: expand clang-tools-manager/README

resolves #351

- adds badges
- adds simple CLI info (with example and copied `--help` output)
---
 clang-tools-manager/README.md | 83 +++++++++++++++++++++++++++++++++--
 cpp-linter/README.md          | 11 ++++-
 2 files changed, 90 insertions(+), 4 deletions(-)

diff --git a/clang-tools-manager/README.md b/clang-tools-manager/README.md
index 7d2d6213..c269bbdc 100644
--- a/clang-tools-manager/README.md
+++ b/clang-tools-manager/README.md
@@ -1,12 +1,89 @@
 # clang-tools-manager
 
+[![crates.io][crates-io-badge]][crates-io-link]
+[![CHANGELOG][changelog-badge]][changelog-link]
+
 A Rust crate to ensure clang-format and/or clang-tidy are installed.
 
-This is a utility for cpp-linter CLI,
-thus its API is considered internal to cpp-linter crate.
+This is a utility for [cpp-linter] CLI,
+thus its API is considered internal to [cpp-linter] crate.
+
+## Binary executable
+
+This crate comes with a `clang-tools` executable binary.
+It can be installed using
+
+```sh
+cargo install clang-tools-manager --locked --features bin
+```
+
+Or using [cargo-binstall] to download pre-built binary executable:
+
+```sh
+cargo binstall clang-tools-manager
+```
 
-To run the binary for this crate (from git source):
+To run the executable from a checked out `git clone`:
 
 ```text
 cargo run --bin clang-tools --features bin -- --help
 ```
+
+[cpp-linter]: https://crates.io/crates/cpp-linter
+[cargo-binstall]: https://github.com/cargo-bins/cargo-binstall
+
+### CLI
+
+The `clang-tools` binary's Command Line Interface (CLI) is rather simple.
+
+<!-- markdownlint-disable MD033 -->
+
+<details><summary><code>clang-tools --help</code></summary>
+<p>
+
+```sh
+Usage: clang-tools [OPTIONS]
+
+Options:
+  -v, --version [<VERSION>]
+          The desired version of clang to install
+
+          [default: ""]
+
+  -V, --verbose
+          Enable verbose logging for debugging purposes.
+
+          This will include more DEBUG level log messages.
+          Without it, log level is set to INFO by default.
+
+  -t, --tool <TOOL>
+          The clang tool to install
+
+          [default: "clang-format clang-tidy"]
+          [possible values: clang-tidy, clang-format]
+
+  -d, --directory <DIRECTORY>
+          The directory where the clang tools should be installed
+
+  -f, --force
+          Force overwriting symlink to the installed binary.
+
+          This will only overwrite an existing symlink.
+
+  -h, --help
+          Print help (see a summary with '-h')
+```
+
+</p>
+</details>
+
+For example, to install version 21 of clang-format and clang-tidy:
+
+```sh
+clang-tools --version 21
+```
+
+[crates-io-badge]: https://img.shields.io/crates/v/clang-tools-manager
+[crates-io-link]: https://crates.io/crates/clang-tools-manager
+[changelog-badge]: https://img.shields.io/badge/keep_a_change_log-v1.1.0-ffec3d
+[changelog-link]: https://github.com/cpp-linter/cpp-linter-rs/tree/main/clang-tools-manager/CHANGELOG.md
diff --git a/cpp-linter/README.md b/cpp-linter/README.md
index bc4d2535..3630df17 100644
--- a/cpp-linter/README.md
+++ b/cpp-linter/README.md
@@ -1,6 +1,10 @@
 
 # cpp-linter
 
+[![crates.io][crates-io-badge]][crates-io-link]
+[![docs.rs][docs-badge]][docs-link]
+[![CHANGELOG][changelog-badge]][changelog-link]
+
 This crate contains the the library used as a backend for the
 `cpp-linter` binary executable. The main focus of `cpp-linter` is as follows:
 
@@ -14,5 +18,10 @@ This crate contains the the library used as a backend for the
 
 See also the [CLI document hosted on github][gh-pages].
 
-[pypi-org]: https://pypi.org/project/cpp-linter
 [gh-pages]: https://cpp-linter.github.io/cpp-linter-rs/cli.html
+[crates-io-badge]: https://img.shields.io/crates/v/cpp-linter
+[crates-io-link]: https://crates.io/crates/cpp-linter
+[docs-badge]: https://img.shields.io/docsrs/cpp-linter
+[docs-link]: https://docs.rs/cpp-linter
+[changelog-badge]: https://img.shields.io/badge/keep_a_change_log-v1.1.0-ffec3d
+[changelog-link]: https://github.com/cpp-linter/cpp-linter-rs/blob/main/cpp-linter/CHANGELOG.md