From 96259528055d0cad4a52c9914e056ad614c821ce Mon Sep 17 00:00:00 2001
From: Samuel Moelius <samuel.moelius@trailofbits.com>
Date: Mon, 10 Jun 2024 14:37:37 -0400
Subject: [PATCH] Add documentation

---
 examples/experimental/README.md  |  1 +
 examples/general/README.md       | 40 ++++++++++++++++++++++++++++++++
 examples/restriction/README.md   |  1 +
 examples/supplementary/README.md |  9 +++++++
 examples/testing/README.md       |  1 +
 5 files changed, 52 insertions(+)
 create mode 100644 examples/experimental/README.md
 create mode 100644 examples/general/README.md
 create mode 100644 examples/restriction/README.md
 create mode 100644 examples/supplementary/README.md
 create mode 100644 examples/testing/README.md

diff --git a/examples/experimental/README.md b/examples/experimental/README.md
new file mode 100644
index 000000000..0e6f15d10
--- /dev/null
+++ b/examples/experimental/README.md
@@ -0,0 +1 @@
+# Experimental lints
diff --git a/examples/general/README.md b/examples/general/README.md
new file mode 100644
index 000000000..f1fe75555
--- /dev/null
+++ b/examples/general/README.md
@@ -0,0 +1,40 @@
+# General-purpose lints
+
+## Use of `dylint_linting`'s `constituent` feature
+
+The general-purpose lints use `dylint_linting`'s [`constituent` feature]. This allows the lints to be built in either of the following two configurations:
+
+- as individual libraries
+- as a single, combined `general` library
+
+However, some additional organization of both the `general` directory and its subdirectories is required.
+
+For the general directory itself:
+
+- Each lint is listed under `[dependencies]` in general/Cargo.toml
+- Each lint is listed under `[workspace.members]` in general/Cargo.toml
+- Each lint's `register_lints` function is called from the `register_lints` function in src/lib.rs.
+
+For each lint subdirectory:
+
+- The following files do not appear, even though they would be created by `cargo dylint new`:
+  - .cargo/config.toml
+  - .gitignore
+  - rust-toolchain
+- The lint's Cargo.toml has the following `[lib]` section (note: `crate-type` is not just `["cdylib"]`):
+  ```toml
+  [lib]
+  crate-type = ["cdylib", "rlib"]
+  ```
+- The lint gets its `clippy_utils` dependency from the workspace, i.e.:
+  ```toml
+  [dependencies]
+  clippy_utils = { workspace = true }
+  ```
+- The lint's Cargo.toml has the following `[features]` section:
+  ```toml
+  [features]
+  rlib = ["dylint_linting/constituent"]
+  ```
+
+[`constituent` feature]: ../../utils/linting/README.md#constituent-feature
diff --git a/examples/restriction/README.md b/examples/restriction/README.md
new file mode 100644
index 000000000..3753eac73
--- /dev/null
+++ b/examples/restriction/README.md
@@ -0,0 +1 @@
+# Restriction lints
diff --git a/examples/supplementary/README.md b/examples/supplementary/README.md
new file mode 100644
index 000000000..c999dc2c0
--- /dev/null
+++ b/examples/supplementary/README.md
@@ -0,0 +1,9 @@
+# Supplementary lints
+
+Like the [general-purpose lints], the supplementary lints use `dylint_linting`'s [`constituent` feature].
+
+See the general-purpose lints' [documentation] for an explanation.
+
+[`constituent` feature]: ../../utils/linting/README.md#constituent-feature
+[documentation]: ../general/README.md
+[general-purpose lints]: ../general
diff --git a/examples/testing/README.md b/examples/testing/README.md
new file mode 100644
index 000000000..e07c53478
--- /dev/null
+++ b/examples/testing/README.md
@@ -0,0 +1 @@
+# Testing lints