From: Ian Jackson <ijackson@chiark.greenend.org.uk>
Date: Sat, 14 May 2022 17:09:18 +0000 (+0100)
Subject: crate structure: Write down the import structure doctrine.
X-Git-Tag: otter-1.1.0~173
X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=commitdiff_plain;h=62d530ed813e592ccc49c33bad76d272bc4e9922;p=otter.git

crate structure: Write down the import structure doctrine.

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>
---

diff --git a/base/crates.rs b/base/crates.rs
index b10733bd..1eb1aa37 100644
--- a/base/crates.rs
+++ b/base/crates.rs
@@ -2,6 +2,8 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
 // There is NO WARRANTY.
 
+// See Import Structure Doctrine in src/prelude.rs
+
 pub use arrayvec;
 pub use derive_more;
 pub use extend;
diff --git a/base/imports.rs b/base/imports.rs
index 5b999183..51b0cc06 100644
--- a/base/imports.rs
+++ b/base/imports.rs
@@ -2,6 +2,8 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
 // There is NO WARRANTY.
 
+// See Import Structure Doctrine in src/prelude.rs
+
 pub use std::borrow::Borrow;
 pub use std::cmp::{max, Ordering};
 pub use std::convert::{TryFrom, TryInto};
diff --git a/base/prelude.rs b/base/prelude.rs
index 3f02473c..b9210e16 100644
--- a/base/prelude.rs
+++ b/base/prelude.rs
@@ -2,5 +2,7 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
 // There is NO WARRANTY.
 
+// See Import Structure Doctrine in src/prelude.rs
+
 pub use crate::crates::*;
 pub use crate::imports::*;
diff --git a/src/crates.rs b/src/crates.rs
index 0df7da8a..75a98c1c 100644
--- a/src/crates.rs
+++ b/src/crates.rs
@@ -2,6 +2,8 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
 // There is NO WARRANTY.
 
+// See Import Structure Doctrine in src/prelude.rs
+
 pub use otter_support;
 
 pub use anyhow;
diff --git a/src/imports.rs b/src/imports.rs
index 19117252..356609ba 100644
--- a/src/imports.rs
+++ b/src/imports.rs
@@ -2,6 +2,8 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
 // There is NO WARRANTY.
 
+// See Import Structure Doctrine in src/prelude.rs
+
 use crate::crates::*;
 use otter_support::crates::*;
 use otter_base::crates::*;
diff --git a/src/prelude.rs b/src/prelude.rs
index de102f01..5f906511 100644
--- a/src/prelude.rs
+++ b/src/prelude.rs
@@ -2,6 +2,31 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
 // There is NO WARRANTY.
 
+
+//! # Import Structure Doctrine:
+//!
+//! The purpose is to let us define our conventional namespace once,
+//! without causing failures due to ambiguity.  (Importing the same name
+//! via different import paths, both with `*`, does not work - the name is
+//! regarded as ambiguous even though the referet is the same.  And the
+//! error messages are hopeless: when this occurs the `*` imports are
+//! simply ineffective for that name and nothing tells you there's an
+//! ambiguity.)
+//!
+//! Each crate has these (public) modules:
+//!
+//!  * `crates`: One `pub use` statement for each dependency crate,
+//!    including the otter crates, providing simply the crate name.
+//!
+//!  * `imports`: `pub use` statements for the names *within* crates that
+//!    *this* crate wants to use, *excluding* any that are in the `imports`
+//!    of this crate's dependencies.  This may `use` various `crates::*` or
+//!    even `imports::*` but *must not* `pub use`.
+//!
+//!  * `prelude`: Brings all the parts together for the use of this crate.
+//!    Should `pub use` the `crates::*` and `imports::*` for this crate
+//!    and the dependencies.  Should not be used elsewhere.
+
 pub use crate::crates::*;
 pub use crate::imports::*;
 
diff --git a/support/crates.rs b/support/crates.rs
index bc76d968..ee60990c 100644
--- a/support/crates.rs
+++ b/support/crates.rs
@@ -2,6 +2,8 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
 // There is NO WARRANTY.
 
+// See Import Structure Doctrine in src/prelude.rs
+
 pub use otter_base;
 
 pub use chrono;
diff --git a/support/imports.rs b/support/imports.rs
index fb422a55..5b7eae4c 100644
--- a/support/imports.rs
+++ b/support/imports.rs
@@ -2,6 +2,8 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
 // There is NO WARRANTY.
 
+// See Import Structure Doctrine in src/prelude.rs
+
 pub use std::collections::{hash_map, HashMap, HashSet};
 pub use std::sync::Arc;
 
diff --git a/support/prelude.rs b/support/prelude.rs
index 8935289a..780fcc2c 100644
--- a/support/prelude.rs
+++ b/support/prelude.rs
@@ -2,6 +2,8 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
 // There is NO WARRANTY.
 
+// See Import Structure Doctrine in src/prelude.rs
+
 pub use crate::crates::*;
 pub use crate::imports::*;