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 b10733bd4add469b10a5dab8c7edf79f5ab88f36..1eb1aa370b24abf314fe03ea56bb5905ecb86113 100644 (file)
--- 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 5b99918311e37cf91bd16710b2e15a41ccef2b6b..51b0cc062d0b168ac6d0007d90bd5c7a4cb0f126 100644 (file)
--- 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 3f02473ccd71442fbaa24407adce87d80ebedd2b..b9210e163566d8ae70934db158411bf5129ced8c 100644 (file)
--- 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 0df7da8a29c656a50df8e19a90b9540de53566ae..75a98c1cccd7f186a5e1ff403d838a93c231c401 100644 (file)
--- 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 19117252dcf7b7bb3e423711900704ebac57cbcb..356609bac6ae3e78217fa4b2ec732d95aa961262 100644 (file)
--- 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 de102f01c95b83f38e557331c8fc4f2692366411..5f906511b2d3e3d7452f557d455636c47f05e613 100644 (file)
--- 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 bc76d96871d1c909728b36aae3ae8e76f813a2bf..ee60990cee2f6e795ee0e4e3b55378c492296182 100644 (file)
--- 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 fb422a5510ca0e2d54730c8e9b2248aec49aaa2e..5b7eae4c8c59a04458d6185e187b814d5ec3bc55 100644 (file)
--- 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 8935289aeb762f086da207ca00bbb968da6ea66d..780fcc2cb4fb1f0b9b8a38346687d8684b8bd76b 100644 (file)
--- 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::*;