docs: ensure docs are well-linked, fed and washed

crates/ir/src/lib.rs

@@ -4,17 +4,14 @@ use serde::{Deserialize, Serialize};
 
 pub mod id;
 pub mod instruction;
-
-// feel free to make this public if there's sufficient reason to do so
-// otherwise, go use the GraphIr in the module this is written in directly instead!!
-mod semi_human;
+pub mod semi_human;
 
 pub type Map<K, V> = ahash::AHashMap<K, V>;
 pub type Set<V> = ahash::AHashSet<V>;
 
 /// Gives you a super well typed graph IR for a given human-readable repr.
 ///
-/// Look at [`SemiHumanGraphIr`] and the test files in the repo at `testfiles/`
+/// Look at [`semi_human::GraphIr`] and the test files in the repo at `testfiles/`
 /// to see what the RON should look like.
 /// No, we don't want you to write out [`GraphIr`] in full by hand.
 /// That's something for the machines to do.
@@ -31,8 +28,7 @@ pub fn from_ron(source: &str) -> ron::error::SpannedResult<GraphIr> {
 ///
 /// Pipelines may not be fully linear. They may branch out and recombine later on.
 /// As such, the representation for them which is currently used is a
-/// [**D**irected **A**cyclic **G**raph](https://en.wikipedia.org/wiki/Directed_acyclic_graph)
-/// .
+/// [**D**irected **A**cyclic **G**raph](https://en.wikipedia.org/wiki/Directed_acyclic_graph).
 ///
 /// For those who are already familiar with graphs, a DAG is one, except that:
 ///

crates/ir/src/semi_human.rs

@@ -2,6 +2,10 @@
 //!
 //! Sacrifices type expressivity for the sake of typability in [RON] files.
 //!
+//! **If you want to construct a graph IR programmatically,
+//! use [`crate::GraphIr`] directly instead,
+//! as it gives you more control to specify where your instructions came from.**
+//!
 //! [RON]: https://docs.rs/ron/latest/ron/
 
 use serde::{Deserialize, Serialize};