docs: bilingual module docs for the foundation layer

crates/apsis-rs/src/lib.rs

@@ -21,6 +21,26 @@
 //! aggregates all other layers and is only needed by simulation workloads,
 //! projects that do not run simulations can enable `ops` instead, which
 //! enables every layer except `sim`.
+//!
+//! ApsisRS：面向商业航天与卫星互联网系统的计算内核。
+//!
+//! 工作区按依赖排序的各层组织：
+//!
+//! ```text
+//! foundation -> physics -> orbit -> rf -> network -> ops -> sim
+//! ```
+//!
+//! 依赖只朝一个方向流动。一层可以使用其左侧的各层，但绝不使用其右侧的
+//! 层。
+//!
+//! 本 crate 是名为 `apsis-rs` 的公共门面。下游项目直接依赖它，并启用与其
+//! 所需层相匹配的特性。每个特性重导出某一层的各 crate，并引入其下方各层
+//! 的特性。例如，`orbit` 特性启用 `physics`，并重导出 [`apsis_orbit`]、
+//! [`apsis_tle`]、[`apsis_sgp4`]、[`apsis_kepler`] 与 [`apsis_ephemeris`]。
+//!
+//! `full` 特性启用每一层，包括 `sim`。因为 `sim` 聚合了其余所有层且只为
+//! 仿真工作负载所需，不运行仿真的项目可以改而启用 `ops`，它启用除 `sim`
+//! 之外的每一层。
 
 #![forbid(unsafe_code)]
 #![deny(missing_docs)]

crates/foundation/apsis-core/src/lib.rs

@@ -20,6 +20,24 @@
 //!   SI units.
 //! - [`Quantity`] marks newtypes that carry a physical unit, so generic
 //!   code can accept any quantity and still recover its unit type.
+//!
+//! ApsisRS 工作区共享的基础类型：一个通用错误类型、结果别名、物理常量，以及
+//! 单位标记 trait。
+//!
+//! 本 crate 位于依赖图的底部。它不依赖任何其他 ApsisRS crate，故其余每个
+//! crate 都可以使用它。
+//!
+//! 这里有三件事：
+//!
+//! - [`Error`] 与 [`Result`] 是携带粗糙 [`ErrorKind`] 的通用错误。它们存在，
+//!   是为了让失败没有有趣结构的函数无需发明一个类型即可报告它，也是为了让
+//!   工作区有一个可退守的形状。它们有意地*不是*各层的错误类型：具有领域
+//!   特定失败的一层会定义自己的 `Error` 与 `ErrorKind`，其变体指名调用方
+//!   想要匹配的具体情形。原因以及各领域错误遵循的约定见
+//!   `docs/design/errors.md`。
+//! - [`constant`] 保存以 SI 单位表达的物理与天文常量。
+//! - [`Quantity`] 标记携带有物理单位的 newtype，使泛型代码可以接受任何量
+//!   并仍能恢复其单位类型。
 
 #![forbid(unsafe_code)]
 #![deny(missing_docs)]

crates/foundation/apsis-core/src/quantity.rs

@@ -9,6 +9,15 @@
 //! of its kind are in the corresponding base unit, which allows conversion
 //! between units of the same dimension. The base unit of a dimension always
 //! has a factor of one.
+//!
+//! 携带有物理单位的量所用的标记 trait。
+//!
+//! 量的 newtype 把数值与其单位一同存在类型中。[`Quantity`] trait 通过关联
+//! 类型公开该单位，故可对任何量编写泛型代码并仍能恢复所给的是哪个单位。
+//!
+//! 单位本身是任何实现 [`Unit`] 的类型。单位知道其同类在相应基本单位中有
+//! 多少个，这允许同一量纲的各单位之间换算。一个量纲的基本单位其因子总是
+//! 一。
 //
 //! 单位本身是任意实现 [`Unit`] 的类型。单位知道自己相当于多少个对应的基本单位，
 //! 从而可以在同一量纲的单位之间换算。某量纲的基本单位其因子恒为一。

crates/foundation/apsis-macros/src/lib.rs

@@ -33,6 +33,32 @@
 //! If the workspace later needs macros that generate items, such as deriving
 //! a set of conversions from one definition, that is the point at which this
 //! crate should gain its first macro.
+//!
+//! 支持 ApsisRS 工作区的宏。
+//!
+//! 本 crate 当前不定义任何宏。它的存在是为了让工作区在需要时有存放宏定义的
+//! 单一位置，也是为了日后再加一个宏时无需新建 crate。
+//!
+//! 让它保持为空的决定源于工作区实际所需。Rust 内建的 `macro_rules!` 已能完成
+//! 基础层所需的一切：
+//!
+//! - 替换一个类型与一个字面量以构建量，如 `quantity!(Meters, 1.5)`。
+//! - 依据尾随记号分派以接受单位后缀，如 `to_meters!(2.5 km)`。
+//!
+//! 两种形式都由 `tests/probe.rs` 中的测试演示。它们可以直接写在用到它们的
+//! crate 中，故无需共享的宏 crate。
+//!
+//! 有两点限制值得记下，因为它们解释了为何不提供基于宏的单位系统：
+//!
+//! - `macro_rules!` 宏不能对不是标识符的单位后缀泛型化。`1.5 m` 与
+//!   `1.5 km` 由不同的规则接受，故该宏必须枚举它所支持的每个后缀。
+//!   `apsis-units` 中的单位 newtype 已在没有该列表的情况下给出编译期单位
+//!   安全，故该宏只会增加表面积而不增加检查。
+//! - 声明式宏无法检视其参数的值，故它无法在常量求值已做的之外于编译期折叠
+//!   单位换算。诸如 `2.5 * 1000.0` 这样的字面量反正会被编译器折叠。
+//!
+//! 若工作区日后需要生成项（例如从一个定义派生一组换算）的宏，那便是本
+//! crate 应获得其第一个宏之时。
 
 #![forbid(unsafe_code)]
 #![deny(missing_docs)]

crates/foundation/apsis-math/src/lib.rs

@@ -24,6 +24,21 @@
 //! let z = x.cross(y);
 //! assert_eq!(z, Vec3::new(0.0, 0.0, 1.0));
 //! ```
+//!
+//! ApsisRS 工作区无依赖的线性代数。
+//!
+//! 本 crate 提供三种类型：
+//!
+//! - [`Vec3`]，基于 `f64` 的三分量列矢量
+//! - [`Quat`]，用于转动的单位四元数
+//! - [`Mat3`]，按列主序存储的三阶矩阵
+//!
+//! 这些类型是纯数据，除各方法上所述外没有内部不变量，故其字段是公开的，
+//! 值可由结构体字面量表达式构建。对某些输入在数学上未定义的操作（如把零
+//! 矢量归一化）返回 [`Option`]，而不 panic 或产生非有限结果。
+//!
+//! 所有转动都绕给定轴采用右手定则，所有角度都以弧度计。输入时角度不进行
+//! 环绕；要求取规范区间的方法会说明该要求。
 
 #![forbid(unsafe_code)]
 #![deny(missing_docs)]

crates/foundation/apsis-math/src/mat3.rs

@@ -1,4 +1,6 @@
 //! Three by three matrices over `f64`.
+//!
+//! 基于 `f64` 的三阶矩阵。
 
 use crate::quat::Quat;
 use crate::vec3::Vec3;

crates/foundation/apsis-math/src/parallel.rs

@@ -27,6 +27,23 @@
 //! let output = map_index(input.len(), |index| input[index] * input[index]);
 //! assert_eq!(output[10], 100.0);
 //! ```
+//!
+//! 仅建立在标准库之上的作用域并行。
+//!
+//! 工作区禁止第三方 crate，故线程池须在此编写。但它并未如此：本工作区中
+//! 受益于多核的操作，全都是对独立项做可并行化的循环，而标准库的作用域线程
+//! 直接表达这些。`std::thread::scope` 借用其数据，故调用方无需原子引用计数
+//! 即可共享切片或读取器，并在返回前 join 每个线程，故没有任何结果会在仍被
+//! 写入时逸出该作用域。
+//!
+//! 入口是 [`for_each_index`]，它把区间按线程切成若干块，并对每个元素运行
+//! 一个闭包。该闭包必须可从另一线程调用，故它所捕获的任何东西都必须是
+//! `Sync` 的；实践中这意味着读取共享输入并写入输出的互不相交槽位，这正是
+//! 此处每个并行循环所具有的形状。
+//!
+//! 因为没有池，一次并行调用的成本包含启动线程。只有当每个线程都有实打实的
+//! 工作时才值得付出，故 [`thread_count`] 报告机器所提供的数量，本工作区中
+//! 的调用方用它来对小的输入跳过并行路径。
 
 use core::hint;
 

crates/foundation/apsis-math/src/quat.rs

@@ -1,4 +1,6 @@
 //! Unit quaternions used for rotations.
+//!
+//! 用于转动的单位四元数。
 
 use crate::vec3::Vec3;
 use core::fmt;

crates/foundation/apsis-math/src/vec3.rs

@@ -1,4 +1,6 @@
 //! Three component vectors over `f64`.
+//!
+//! 基于 `f64` 的三分量矢量。
 
 use core::fmt;
 use core::ops::{Add, AddAssign, Div, DivAssign, Mul, MulAssign, Neg, Sub, SubAssign};