docs: bilingual comments for the decibel and gain scales

crates/rf/apsis-rf/src/decibel.rs

@@ -4,6 +4,8 @@ use core::fmt;
 
 /// A ratio expressed in decibels.
 ///
+/// 以分贝表示的比值。
+///
 /// A decibel is ten times the base ten logarithm of a power ratio, so a
 /// value of zero is unity gain or loss, a value of three is very close to a
 /// doubling, and a value of minus three is very close to a halving.
@@ -16,18 +18,26 @@ pub struct Decibel(f64);
 
 impl Decibel {
     /// The value for a ratio of one, which is zero decibels.
+    ///
+    /// 比值为一时的取值，即零分贝。
     pub const UNITY: Self = Self(0.0);
 
     /// The value for a ratio of two, which is about 3.0103 decibels.
+    ///
+    /// 比值为二时的取值，约为 3.0103 分贝。
     pub const DOUBLING: Self = Self(3.010_299_956_639_812);
 
     /// Creates a value from a decibel reading.
+    ///
+    /// 由分贝读数创建一个取值。
     pub const fn from_db(decibels: f64) -> Self {
         Self(decibels)
     }
 
     /// Creates a value from a power ratio.
     ///
+    /// 由功率比创建一个取值。
+    ///
     /// Returns `None` when the ratio is not positive and finite, because the
     /// logarithm is not defined there.
     pub fn from_ratio(ratio: f64) -> Option<Self> {
@@ -40,6 +50,8 @@ impl Decibel {
 
     /// Creates a value from an amplitude ratio.
     ///
+    /// 由幅度比创建一个取值。
+    ///
     /// An amplitude, unlike a power, scales the decibel value by twenty
     /// rather than ten, because power is proportional to amplitude squared.
     /// Use this for a voltage or field ratio.
@@ -56,16 +68,22 @@ impl Decibel {
     }
 
     /// Returns the reading in decibels.
+    ///
+    /// 返回该分贝读数。
     pub const fn db(self) -> f64 {
         self.0
     }
 
     /// Returns the power ratio this reading represents.
+    ///
+    /// 返回该读数所表示的功率比。
     pub fn ratio(self) -> f64 {
         10f64.powf(self.0 / 10.0)
     }
 
     /// Returns the amplitude ratio this reading represents.
+    ///
+    /// 返回该读数所表示的幅度比。
     pub fn amplitude_ratio(self) -> f64 {
         10f64.powf(self.0 / 20.0)
     }
@@ -74,6 +92,11 @@ impl Decibel {
     ///
     /// Adding decibel values multiplies the ratios they represent, which is
     /// how a cascade of gains and losses is combined.
+    ///
+    /// 返回两个读数之和。
+    ///
+    /// 分贝值相加即其所表示的比值相乘，这正是级联增益与损耗的合成
+    /// 方式。
     pub const fn plus(self, other: Self) -> Self {
         Self(self.0 + other.0)
     }
@@ -82,16 +105,24 @@ impl Decibel {
     ///
     /// Subtracting decibel values divides the ratios they represent, which
     /// is how a loss is removed from a gain.
+    ///
+    /// 返回两个读数之差。
+    ///
+    /// 分贝值相减即其所表示的比值相除，这正是从增益中去掉损耗的方式。
     pub const fn minus(self, other: Self) -> Self {
         Self(self.0 - other.0)
     }
 
     /// Returns this reading negated, which inverts the ratio.
+    ///
+    /// 返回该读数的相反数，即比值的倒数。
     pub const fn negated(self) -> Self {
         Self(-self.0)
     }
 
     /// Returns `true` when the reading is finite.
+    ///
+    /// 当该读数有限时返回 `true`。
     pub const fn is_finite(self) -> bool {
         self.0.is_finite()
     }

crates/rf/apsis-rf/src/gain.rs

@@ -12,12 +12,22 @@ use core::fmt;
 /// value is what the `dBd` and `dBi` conventions are defined against. This
 /// crate uses the conventional value so that a conversion between the two
 /// named forms is exact, and it derives the linear ratio from it.
+///
+/// 半波振子相对各向同性辐射体的增益，单位为分贝。
+///
+/// 理想半波振子的精确方向性为 1.6409，即 2.1509 dB。工程实践将其取整为
+/// 2.15 dB，`dBd` 与 `dBi` 两种约定即以该取整值定义。本 crate 采用
+/// 该约定值，使两种具名形式之间的换算精确，并由其导出线性比值。
 pub const DIPOLE_OVER_ISOTROPIC_DB: f64 = 2.15;
 
 /// The linear gain ratio of a half wave dipole, `10^(2.15 / 10)`.
 ///
 /// This is about 1.64059, within 0.02 percent of the exact directivity of an
 /// ideal dipole, which is 1.6409.
+///
+/// 半波振子的线性增益比值，`10^(2.15 / 10)`。
+///
+/// 该值约为 1.64059，与理想振子 1.6409 的精确方向性相差在 0.02% 以内。
 pub const HALF_WAVE_DIPOLE_RATIO: f64 = 1.640_589_773_199_539_4;
 
 /// An antenna gain expressed as a ratio to an isotropic radiator.
@@ -30,6 +40,15 @@ pub const HALF_WAVE_DIPOLE_RATIO: f64 = 1.640_589_773_199_539_4;
 ///   every direction.
 /// - `dBd` is the ratio to a half wave dipole, which is
 ///   [`DIPOLE_OVER_ISOTROPIC_DB`] decibels above an isotropic radiator.
+///
+/// 以相对各向同性辐射体的比值表示的天线增益。
+///
+/// 该类型以线性比值存储。两种具名分贝形式以换算形式提供，因为这一
+/// 选择关乎约定而非增益本身：
+///
+/// - `dBi` 是相对各向同性辐射体的比值，后者向各方向均匀辐射。
+/// - `dBd` 是相对半波振子的比值，后者比各向同性辐射体高
+///   [`DIPOLE_OVER_ISOTROPIC_DB`] 分贝。
 #[derive(Debug, Clone, Copy, PartialEq, PartialOrd)]
 pub struct Gain(f64);
 
@@ -38,6 +57,10 @@ impl Default for Gain {
     ///
     /// This is written by hand rather than derived, because the default for
     /// a ratio type is not its zero but its unit.
+    ///
+    /// 返回单位增益，与 [`Gain::ISOTROPIC`] 相同。
+    ///
+    /// 此处手写而非推导，因为比值类型的缺省值不是其零而是其单位。
     fn default() -> Self {
         Self::ISOTROPIC
     }
@@ -45,12 +68,20 @@ impl Default for Gain {
 
 impl Gain {
     /// Unit gain, as an isotropic radiator has.
+    ///
+    /// 单位增益，如各向同性辐射体所有。
     pub const ISOTROPIC: Self = Self(1.0);
 
     /// The gain of a half wave dipole, about 1.6406.
+    ///
+    /// 半波振子的增益，约为 1.6406。
     pub const HALF_WAVE_DIPOLE: Self = Self(HALF_WAVE_DIPOLE_RATIO);
 
     /// Creates a gain from a linear ratio.
+    ///
+    /// 由线性比值创建增益。
+    ///
+    /// 由线性比值创建增益。
     pub const fn from_ratio(ratio: f64) -> Self {
         Self(ratio)
     }
@@ -59,6 +90,10 @@ impl Gain {
     /// radiator.
     ///
     /// A gain ratio is never negative, so any finite reading is accepted.
+    ///
+    /// 由相对各向同性辐射体的分贝值创建增益。
+    ///
+    /// 增益比值不会为负，故任何有限读数都被接受。
     pub fn from_dbi(dbi: f64) -> Option<Self> {
         if !dbi.is_finite() {
             return None;
@@ -70,6 +105,10 @@ impl Gain {
     /// dipole.
     ///
     /// Returns `None` when the reading is not finite.
+    ///
+    /// 由相对半波振子的分贝值创建增益。
+    ///
+    /// 该读数非有限时返回 `None`。
     pub fn from_dbd(dbd: f64) -> Option<Self> {
         if !dbd.is_finite() {
             return None;
@@ -78,6 +117,8 @@ impl Gain {
     }
 
     /// Returns the linear ratio to an isotropic radiator.
+    ///
+    /// 返回相对各向同性辐射体的线性比值。
     pub const fn ratio(self) -> f64 {
         self.0
     }

crates/rf/apsis-rf/src/power.rs

@@ -6,12 +6,21 @@ use core::fmt;
 /// The reference power of the decibel watt, one watt.
 ///
 /// A power quoted in dBW is a ratio to this value.
+///
+/// 分贝瓦的参考功率，即一瓦。
+///
+/// 以 dBW 表示的功率是相对该值的比值。
 pub const DBW_REFERENCE: f64 = 1.0;
 
 /// The reference power of the decibel milliwatt, one milliwatt.
 ///
 /// A power quoted in dBm is a ratio to this value, so a value in dBm is
 /// thirty decibels above the same value in dBW.
+///
+/// 分贝毫瓦的参考功率，即一毫瓦。
+///
+/// 以 dBm 表示的功率是相对该值的比值，故同一数值以 dBm 表示比以 dBW
+/// 表示高三十分贝。
 pub const DBM_REFERENCE: f64 = 1.0e-3;
 
 /// A power level in watts.
@@ -19,24 +28,39 @@ pub const DBM_REFERENCE: f64 = 1.0e-3;
 /// The type stores watts, which is the unit the decibel references are
 /// defined against, and offers conversion to and from the two decibel forms
 /// used in link budgets.
+///
+/// 以瓦特表示的功率电平。
+///
+/// 该类型以瓦特存储，这是分贝参考所依据的单位，并提供与链路预算中常用
+/// 的两种分贝形式之间的换算。
 #[derive(Debug, Clone, Copy, PartialEq, PartialOrd, Default)]
 pub struct Power(f64);
 
 impl Power {
     /// The reference power of zero dBW, one watt.
+    ///
+    /// 零 dBW 的参考功率，即一瓦。
     pub const WATT: Self = Self(1.0);
 
     /// The reference power of zero dBm, one milliwatt.
+    ///
+    /// 零 dBm 的参考功率，即一毫瓦。
     pub const MILLIWATT: Self = Self(1.0e-3);
 
     /// Creates a power level from a value in watts.
     ///
     /// A power may be zero, which represents no power, but not negative.
+    ///
+    /// 以瓦特值创建功率电平。
+    ///
+    /// 功率可以为零，表示没有功率，但不可为负。
     pub const fn from_watts(watts: f64) -> Self {
         Self(watts)
     }
 
     /// Creates a power level from a value in milliwatts.
+    ///
+    /// 以毫瓦值创建功率电平。
     pub const fn from_milliwatts(milliwatts: f64) -> Self {
         Self(milliwatts * 1.0e-3)
     }
@@ -45,6 +69,10 @@ impl Power {
     ///
     /// A zero or negative reading cannot be expressed as a finite power, so
     /// no validation is needed.
+    ///
+    /// 以分贝瓦值创建功率电平。
+    ///
+    /// 零或负的读数无法表示为有限功率，故无需校验。
     pub fn from_dbw(decibel_watts: f64) -> Option<Self> {
         if !decibel_watts.is_finite() {
             return None;
@@ -55,6 +83,10 @@ impl Power {
     /// Creates a power level from a value in decibel milliwatts.
     ///
     /// Returns `None` when the reading is not finite.
+    ///
+    /// 以分贝毫瓦值创建功率电平。
+    ///
+    /// 该读数非有限时返回 `None`。
     pub fn from_dbm(decibel_milliwatts: f64) -> Option<Self> {
         if !decibel_milliwatts.is_finite() {
             return None;
@@ -63,11 +95,15 @@ impl Power {
     }
 
     /// Returns this power in watts.
+    ///
+    /// 返回该功率的瓦特值。
     pub const fn watts(self) -> f64 {
         self.0
     }
 
     /// Returns this power in milliwatts.
+    ///
+    /// 返回该功率的毫瓦值。
     pub const fn milliwatts(self) -> f64 {
         self.0 * 1.0e3
     }
@@ -76,6 +112,10 @@ impl Power {
     ///
     /// Returns `None` when the power is not positive, because the logarithm
     /// is not defined there.
+    ///
+    /// 返回该功率的分贝瓦值。
+    ///
+    /// 功率非正时返回 `None`，因为对数在那里没有定义。
     pub fn dbw(self) -> Option<f64> {
         if self.0 > 0.0 && self.0.is_finite() {
             Some(10.0 * (self.0 / DBW_REFERENCE).log10())
@@ -87,6 +127,10 @@ impl Power {
     /// Returns this power in decibel milliwatts.
     ///
     /// Returns `None` when the power is not positive.
+    ///
+    /// 返回该功率的分贝毫瓦值。
+    ///
+    /// 功率非正时返回 `None`。
     pub fn dbm(self) -> Option<f64> {
         if self.0 > 0.0 && self.0.is_finite() {
             Some(10.0 * (self.0 / DBM_REFERENCE).log10())
@@ -115,6 +159,10 @@ impl Power {
     ///
     /// Returns `None` when the resulting power is not finite, which happens
     /// for a very large gain.
+    ///
+    /// 返回该功率按某个分贝比值缩放后的值。
+    ///
+    /// 结果功率非有限时返回 `None`；增益极大时即如此。
     pub fn scaled(self, ratio: Decibel) -> Option<Self> {
         if self.0 == 0.0 {
             return Some(self);
@@ -124,6 +172,8 @@ impl Power {
     }
 
     /// Returns `true` when the power is finite and not negative.
+    ///
+    /// 当该功率有限且非负时返回 `true`。
     pub const fn is_valid(self) -> bool {
         self.0.is_finite() && self.0 >= 0.0
     }