Add improvement around doctests on binary crates

Qkessler · Dec 2, 2023 · 62728b0 · 62728b0
1 parent ba4e7f5
commit 62728b0
Show file tree

Hide file tree

Showing 2 changed files with 13 additions and 3 deletions.
diff --git a/.github/DOCS.md b/.github/DOCS.md
@@ -45,3 +45,16 @@ matrix:
 ```
 
 As of today, we don't support Windows, or at least the tests are failing. We can iterate on this and if we feel Windows should be supported in the near feature, we can add `windows-latest` to run CI on it.
+
+### Doctests on --bin crates
+
+As suggested by [issue](https://github.com/rust-lang/rust/issues/50784), doctests won't currently run on Binary creates. I don't see anything particularly wrong with running doctests on binary crates. Some of the argumenst include that "Why would a binary be documented?". Documentation is not only useful for consumers of the library, but rather also internal developers that are maintaining it, looking for better understanding of the binary crate. It's key that developers onboarding into the project have the material to have a swift ramp-up process, to move the project forward. 
+
+Once the issue above is stabilized, we can add the following to the test.yml fire:
+
+```yaml
+# https://github.com/rust-lang/cargo/issues/6669
+- name: cargo test --doc
+  run: cargo test --locked --all-features --doc
+```
+
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
@@ -42,9 +42,6 @@ jobs:
       # https://twitter.com/jonhoo/status/1571290371124260865
       - name: cargo test --locked
         run: cargo test --locked --all-features --all-targets
-      # https://github.com/rust-lang/cargo/issues/6669
-      - name: cargo test --doc
-        run: cargo test --locked --all-features --doc
   minimal:
     # This action chooses the oldest version of the dependencies permitted by Cargo.toml to ensure
     # that this crate is compatible with the minimal version that this crate and its dependencies