Skip to content

Commit fd2dc48

Browse files
authored
Update doc comments and add a few sanity asserts (#72)
1 parent 091c25b commit fd2dc48

File tree

7 files changed

+81
-26
lines changed

7 files changed

+81
-26
lines changed

src/coords.rs

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,7 @@
4040
//! convergence rates compared to the quadratic rate of convergence seen with
4141
//! the more common algortihms based on the Newton-Raphson method.
4242
//!
43-
//! References:
43+
//! # References
4444
//! * "A comparison of methods used in rectangular to Geodetic Coordinates
4545
//! Transformations", Burtch R. R. (2006), American Congress for Surveying
4646
//! and Mapping Annual Conference. Orlando, Florida.

src/ephemeris.rs

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -262,8 +262,8 @@ impl Ephemeris {
262262
///
263263
/// `tot_tow` Is the time of transmission
264264
///
265-
/// References:
266-
/// -# IS-GPS-200D, Section 20.3.2 and Figure 20-1
265+
/// # References
266+
/// * IS-GPS-200D, Section 20.3.2 and Figure 20-1
267267
pub fn decode_gps(frame_words: &[[u32; 8]; 3], tot_tow: f64) -> Ephemeris {
268268
let mut e = Ephemeris::default();
269269
unsafe {

src/ionosphere.rs

Lines changed: 3 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -13,8 +13,7 @@
1313
//! parameters are broadcast by the GPS constellation. A function to decode the
1414
//! parameters from the raw subframe is provided.
1515
//!
16-
//! --------
17-
//! References:
16+
//! # References
1817
//! * IS-GPS-200H, Section 20.3.3.5.2.5 and Figure 20-4
1918
2019
use crate::{c_bindings, time::GpsTime};
@@ -75,9 +74,8 @@ impl Ionosphere {
7574
///
7675
/// In inputs are the word values from Subframe 4 page 18.
7776
///
78-
/// --------
79-
/// References:
80-
/// * IS-GPS-200H, Section 20.3.3.5.1.7
77+
/// # References
78+
/// * IS-GPS-200H, Section 20.3.3.5.1.7
8179
pub fn decode_parameters(words: &[u32; 8]) -> Result<Ionosphere, IonoDecodeFailure> {
8280
let mut iono = Ionosphere(c_bindings::ionosphere_t {
8381
toa: GpsTime::unknown(),

src/signal.rs

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -349,7 +349,7 @@ impl Code {
349349
}
350350
}
351351

352-
/// Attempts to make a `Code` from a string
352+
/// Attempts to make a [`Code`] from a string
353353
pub fn from_c_str(s: &ffi::CStr) -> Result<Code, InvalidCode> {
354354
Self::from_code_t(unsafe { c_bindings::code_string_to_enum(s.as_ptr()) })
355355
}
@@ -359,7 +359,7 @@ impl Code {
359359
c_str.to_string_lossy()
360360
}
361361

362-
/// Gets the corresponding `Constellation`
362+
/// Gets the corresponding [`Constellation`]
363363
pub fn to_constellation(&self) -> Constellation {
364364
Constellation::from_constellation_t(unsafe {
365365
c_bindings::code_to_constellation(self.to_code_t())
@@ -418,7 +418,7 @@ impl std::convert::TryFrom<u8> for Code {
418418
#[derive(Debug, Copy, Clone, Ord, PartialOrd, Eq, PartialEq, Hash)]
419419
pub struct GnssSignal(c_bindings::gnss_signal_t);
420420

421-
/// Invalid values when creating a `GnssSignal` object
421+
/// Invalid values when creating a [`GnssSignal`] object
422422
#[derive(Debug, Copy, Clone, Ord, PartialOrd, Eq, PartialEq, Hash)]
423423
pub enum InvalidGnssSignal {
424424
/// The code integer value was invalid

src/solver.rs

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -83,7 +83,6 @@ impl GnssSolution {
8383
/// in x, y, z (all receiver clock covariance terms are ignored).
8484
///
8585
/// Index 6 is the GDOP.
86-
///
8786
pub fn err_cov(&self) -> Option<&[f64; 7]> {
8887
if self.pos_valid() {
8988
Some(&self.0.err_cov)

src/time.rs

Lines changed: 71 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,43 @@
66
//! weeks since the start of GPS time, and a time of week counting the number of
77
//! seconds since the beginning of the week. In GPS time the week begins at
88
//! midnight on Sunday.
9+
//!
10+
//! [`GpsTime`] is the primary representation used in swiftnav-rs. Other time bases
11+
//! are available, such as [`Utctime`], [`GalTime`], [`BdsTime`], and [`GloTime`]
12+
//! along with conversions for all of these to and from [`GpsTime`].
13+
//! Not all functionality is available in these other representations, so it's
14+
//! intended that all times are to converted to [`GpsTime`] before use with
15+
//! swiftnav-rs.
16+
//!
17+
//! # ⚠️ 🦘 ⏱ ⚠️ - Leap Seconds
18+
//! UTC time occasinally adds additional seconds to keep it synchronized with the
19+
//! slowly changing spin of the earth. This complicates time keeping, so most
20+
//! GNSS time bases ignore leap seconds and thus slowly grow out of sync with UTC.
21+
//! This is fine when dealing with GNSS data, but it's common that people want time
22+
//! to be represented as a UTC time since that's what people are more familiar with.
23+
//! swiftnav-rs provides ways to convert to and from UTC synchronized time bases
24+
//! and is able to correctly compensate for leap seconds in two ways.
25+
//!
26+
//! The first is by using the UTC conversion parameters broadcast by GNSS systems
27+
//! that receivers can decode. [`UtcParams`] is how swiftnav-rs represents this
28+
//! information, and [`UtcParams::decode()`] is provided for decoding the raw GPS
29+
//! navigation subframe with this information. This is the prefered method since it
30+
//! is usually available when processing raw GNSS data and ensures that the right
31+
//! offset is applied at the right time.
32+
//!
33+
//! The second way is to use a table of historical leap seconds that is compiled
34+
//! in to swftnav-rs. This list is kept up to date in the source code as new leap
35+
//! seconds are announced, but once the code is compiled there is no way to update
36+
//! this table with new leap seconds. This obviously means that sooner or later
37+
//! the hard coded leap second information will become out of date and the
38+
//! converted times will be inaccurate. This is fine if you are processing
39+
//! historical data, but processing live data runs the risk of an incorrect time
40+
//! conversion.
41+
//!
42+
//! When converting to or from a time base that uses leap seconds (i.e. [`UtcTime`]
43+
//! and [`GloTime`]) two functions are always provided, one which takes a
44+
//! [`UtcParams`] object to handle the leap second conversion and one which doesn't
45+
//! take a [`UtcParams`] object but has `_hardcoded` appended to the function name.
946
1047
use crate::c_bindings;
1148
use std::error::Error;
@@ -34,9 +71,12 @@ pub const BDS_TIME_START: GpsTime = GpsTime::new_unchecked(
3471
pub const GLO_TIME_START: GpsTime =
3572
GpsTime::new_unchecked(c_bindings::GLO_EPOCH_WN as i16, c_bindings::GLO_EPOCH_TOW);
3673

74+
/// Error type when a given GPS time is not valid
3775
#[derive(Debug, Copy, Clone, PartialOrd, PartialEq)]
3876
pub enum InvalidGpsTime {
77+
/// Indicates an invalid week number was given, with the invalid value returned
3978
InvalidWN(i16),
79+
/// Indicates an invalid time of week was given, with the invalid value returned
4080
InvalidTOW(f64),
4181
}
4282

@@ -121,7 +161,12 @@ impl GpsTime {
121161
}
122162

123163
/// Converts the GPS time into UTC time
164+
///
165+
/// # Panics
166+
/// This function will panic if the GPS time is not valid
124167
pub fn to_utc(self, utc_params: &UtcParams) -> UtcTime {
168+
assert!(self.is_valid());
169+
125170
let mut utc = UtcTime::default();
126171
unsafe {
127172
c_bindings::gps2utc(self.c_ptr(), utc.mut_c_ptr(), utc_params.c_ptr());
@@ -132,9 +177,15 @@ impl GpsTime {
132177
/// Converts the GPS time into UTC time using the hardcoded list of leap
133178
/// seconds.
134179
///
135-
/// Note: The hard coded list of leap seconds will get out of date, it is
180+
/// # ⚠️ 🦘 ⏱ ⚠️ - Leap Seconds
181+
/// The hard coded list of leap seconds will get out of date, it is
136182
/// preferable to use [`GpsTime::to_utc()`] with the newest set of UTC parameters
183+
///
184+
/// # Panics
185+
/// This function will panic if the GPS time is not valid
137186
pub fn to_utc_hardcoded(self) -> UtcTime {
187+
assert!(self.is_valid());
188+
138189
let mut utc = UtcTime::default();
139190
unsafe {
140191
c_bindings::gps2utc(self.c_ptr(), utc.mut_c_ptr(), std::ptr::null());
@@ -150,8 +201,9 @@ impl GpsTime {
150201
/// Gets the number of seconds difference between GPS and UTC using the hardcoded
151202
/// list of leap seconds
152203
///
153-
/// Note: The hard coded list of leap seconds will get out of date, it is
154-
/// preferable to use [`GpsTime::utc_offset_hardcoded()`] with the newest set
204+
/// # ⚠️ 🦘 ⏱ ⚠️ - Leap Seconds
205+
/// The hard coded list of leap seconds will get out of date, it is
206+
/// preferable to use [`GpsTime::utc_offset()`] with the newest set
155207
/// of UTC parameters
156208
pub fn utc_offset_hardcoded(&self) -> f64 {
157209
unsafe { c_bindings::get_gps_utc_offset(self.c_ptr(), std::ptr::null()) }
@@ -165,8 +217,9 @@ impl GpsTime {
165217
/// Checks to see if this point in time is a UTC leap second event using the
166218
/// hardcoded list of leap seconds
167219
///
168-
/// Note: The hard coded list of leap seconds will get out of date, it is
169-
/// preferable to use [`GpsTime::is_leap_second_event_hardcoded()`] with the newest
220+
/// # ⚠️ 🦘 ⏱ ⚠️ - Leap Seconds
221+
/// The hard coded list of leap seconds will get out of date, it is
222+
/// preferable to use [`GpsTime::is_leap_second_event()`] with the newest
170223
/// set of UTC parameters
171224
pub fn is_leap_second_event_hardcoded(&self) -> bool {
172225
unsafe { c_bindings::is_leap_second_event(self.c_ptr(), std::ptr::null()) }
@@ -229,7 +282,8 @@ impl GpsTime {
229282
/// Converts a GPS time into a Glonass time using the hardcoded list of leap
230283
/// seconds.
231284
///
232-
/// Note: The hard coded list of leap seconds will get out of date, it is
285+
/// # ⚠️ 🦘 ⏱ ⚠️ - Leap Seconds
286+
/// The hard coded list of leap seconds will get out of date, it is
233287
/// preferable to use [`GpsTime::to_glo()`] with the newest set of UTC parameters
234288
///
235289
/// # Panics
@@ -486,7 +540,7 @@ impl GloTime {
486540
}
487541
}
488542

489-
/// Structure containing GPS UTC correction parameters
543+
/// GPS UTC correction parameters
490544
#[derive(Clone)]
491545
pub struct UtcParams(c_bindings::utc_params_t);
492546

@@ -499,13 +553,13 @@ impl UtcParams {
499553
&self.0
500554
}
501555

502-
/// Decodes UTC parameters from GLS LNAV message subframe 4 words 6-10.
556+
/// Decodes UTC parameters from GPS LNAV message subframe 4 words 6-10.
503557
///
504558
/// Note: Fills out the full time of week from current gps week cycle. Also
505559
/// sets t_lse to the exact GPS time at the start of the leap second event.
506560
///
507-
/// References:
508-
/// -# IS-GPS-200H, Section 20.3.3.5.1.6
561+
/// # References
562+
/// * IS-GPS-200H, Section 20.3.3.5.1.6
509563
pub fn decode(words: &[u32; 8]) -> Option<Self> {
510564
let mut params = UtcParams::default();
511565
let result = unsafe { c_bindings::decode_utc_parameters(words, params.mut_c_ptr()) };
@@ -518,6 +572,9 @@ impl UtcParams {
518572
}
519573

520574
/// Build the UTC parameters from the already decoded parameters
575+
///
576+
/// # Panics
577+
/// This function will panic if either `tot` or `t_lse` are not valid
521578
pub fn from_components(
522579
a0: f64,
523580
a1: f64,
@@ -527,6 +584,8 @@ impl UtcParams {
527584
dt_ls: i8,
528585
dt_lsf: i8,
529586
) -> UtcParams {
587+
assert!(tot.is_valid() && t_lse.is_valid());
588+
530589
let tot = tot.to_gps_time_t();
531590
let t_lse = t_lse.to_gps_time_t();
532591
UtcParams(c_bindings::utc_params_t {
@@ -576,7 +635,7 @@ impl Default for UtcParams {
576635
}
577636
}
578637

579-
/// Structure representing UTC time
638+
/// Representation of UTC time
580639
///
581640
/// Note: This implementation does not aim to be able to represent arbitrary dates and times.
582641
/// It is only meant to represent dates and times over the period that GNSS systems have been
@@ -722,7 +781,7 @@ impl<Tz: chrono::offset::TimeZone> From<chrono::DateTime<Tz>> for UtcTime {
722781
}
723782
}
724783

725-
/// Structure representing a modified julian date (MJD)
784+
/// Representation of modified julian dates (MJD)
726785
#[derive(Copy, Clone, Debug, PartialEq, PartialOrd)]
727786
pub struct MJD(f64);
728787

src/troposphere.rs

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -12,8 +12,7 @@
1212
//! Tropospheric delays are typically modeled with the UNM3m model. The model
1313
//! parameters are hardcoded into the library, unlike the ionosphere model.
1414
//!
15-
//! -----------
16-
//! References:
15+
//! # References
1716
//! * UNB Neutral Atmosphere Models: Development and Performance. R Leandro,
1817
//! M Santos, and R B Langley
1918
use crate::{c_bindings, coords::ECEF, navmeas::NavigationMeasurement, time::GpsTime};

0 commit comments

Comments
 (0)