From 30c9a348c3df210fa3e9e207e096e629c9e2aab5 Mon Sep 17 00:00:00 2001 From: ApsisRS contributors Date: Fri, 2 Oct 2026 01:16:30 +0800 Subject: [PATCH] docs: bilingual comments for the decibel and gain scales --- crates/rf/apsis-rf/src/decibel.rs | 31 +++++++++++++++++++ crates/rf/apsis-rf/src/gain.rs | 41 +++++++++++++++++++++++++ crates/rf/apsis-rf/src/power.rs | 50 +++++++++++++++++++++++++++++++ 3 files changed, 122 insertions(+) diff --git a/crates/rf/apsis-rf/src/decibel.rs b/crates/rf/apsis-rf/src/decibel.rs index 2349d4c..3d3cc29 100644 --- a/crates/rf/apsis-rf/src/decibel.rs +++ b/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 { @@ -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() } diff --git a/crates/rf/apsis-rf/src/gain.rs b/crates/rf/apsis-rf/src/gain.rs index 04823a3..4c6313f 100644 --- a/crates/rf/apsis-rf/src/gain.rs +++ b/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 { 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 { 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 } diff --git a/crates/rf/apsis-rf/src/power.rs b/crates/rf/apsis-rf/src/power.rs index 2248c67..6ea7dca 100644 --- a/crates/rf/apsis-rf/src/power.rs +++ b/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 { 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 { 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 { 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 { 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 { 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 }