Fix API documentation issues

Author: mshroyer

CHANGELOG.md

@@ -1,5 +1,9 @@
 # CoursePointer Changelog
 
+## v0.3.1
+
+- Fix issues with rust docs.
+
 ## v0.3.0
 
 - Made the `course` module a public library that can be used to build courses

Cargo.lock

@@ -1,7 +1,7 @@
 [package]
 name = "coursepointer"
 description = "Converts waypoints into Garmin FIT course points"
-version = "0.3.0"
+version = "0.3.1"
 edition = "2024"
 rust-version = "1.85"
 default-run = "coursepointer"

Cargo.toml

@@ -1,6 +1,6 @@
 [project]
 name = "coursepointer"
-version = "0.3.0"
+version = "0.3.1"
 description = "Add your description here"
 requires-python = ">=3.13"
 dependencies = [

pyproject.toml

@@ -49,10 +49,10 @@
 //!
 //! # Units of measure
 //!
-//! Courses and related types here us zero-cost unit of measure types from
+//! Courses and related types here use zero-cost unit of measure types from
 //! [dimensioned](https://docs.rs/dimensioned/latest/dimensioned/) to avoid type
-//! confusion of speed and distance quantities, and analogous types implemented
-//! here for angular degrees.
+//! confusion of speed and distance quantities, and analogous types are
+//! implemented here for angular degrees.
 //!
 //! You can obtain a dimensional quantity by multiplying a constant representing
 //! the unit of measure, for example:
@@ -157,13 +157,21 @@ impl Default for CourseSetOptions {
 }
 
 impl CourseSetOptions {
+    /// Sets the threshold distance for course point interception
+    ///
+    /// Sets a distance, in meters, below which a waypoint may be considered to
+    /// "intercept" a route, turning it into a course point.
     pub fn with_threshold(self, threshold: Meter<f64>) -> Self {
         Self {
             threshold,
             strategy: self.strategy,
         }
     }
 
+    /// Set strategy for handling duplicate intercepts
+    ///
+    /// Controls how waypoints that intercept the route multiple times (within
+    /// the threshold) are handled.
     pub fn with_strategy(self, strategy: InterceptStrategy) -> Self {
         Self {
             threshold: self.threshold,
@@ -172,7 +180,7 @@ impl CourseSetOptions {
     }
 }
 
-/// A set of [`Course`]s and their associated course points.
+/// A collection of [`Course`]s and their associated course points.
 pub struct CourseSet {
     /// Courses with any associated course points.
     pub courses: Vec<Course>,
@@ -664,8 +672,8 @@ impl<'a> SegmentedCourseBuilder<'a> {
 /// A course record
 ///
 /// Represents a single point along a course, analogous to a route point or a
-/// track point.  However, a course record additionally contains the points'
-/// cumulative distances along the course.
+/// track point.  However, in contrast with a route point, a course record
+/// additionally contains the points' cumulative distances along the course.
 #[derive(Clone, PartialEq, Debug)]
 pub struct Record {
     /// Position including optional elevation
@@ -715,8 +723,8 @@ impl TryFrom<Waypoint<GeoPoint>> for Waypoint<GeoAndXyzPoint> {
 pub struct CoursePoint {
     /// Position of the point's interception with the course
     ///
-    /// Note that this is calculated as interception from the waypoint, so the
-    /// course point's position can be different from that of the original
+    /// Note that this is calculated as the interception from the waypoint, so
+    /// the course point's position can be different from that of the original
     /// waypoint.
     pub point: GeoPoint,
 

src/course.rs

@@ -322,7 +322,7 @@ impl DefinitionFrame {
     }
 }
 
-/// Course point types
+/// Sport types
 ///
 /// Names and numeric values manually copied from Profile.xlsx in FIT SDK
 /// 21.171.00.
@@ -749,7 +749,7 @@ fn timedelta_from_seconds(s: Second<f64>) -> Result<TimeDelta> {
     ))
 }
 
-/// Options for writing a FIT course.
+/// Options for writing a FIT course
 #[derive(Clone, Debug)]
 pub struct FitCourseOptions {
     speed: MeterPerSecond<f64>,
@@ -761,7 +761,7 @@ pub struct FitCourseOptions {
 }
 
 impl FitCourseOptions {
-    /// Write the fit file using the given speed for record timestamps
+    /// Write the FIT file using the given speed for record timestamps
     ///
     /// This has the effect of setting the speed of the Virtual Partner on
     /// compatible Garmin devices.
@@ -772,16 +772,16 @@ impl FitCourseOptions {
 
     /// Set the timestamp at which the course starts
     ///
-    /// Controls the timestamps on lap and record messages.  An arbitrary but
-    /// consistent time will be used if left unset.
+    /// Controls the timestamps on lap and record messages.  An arbitrary, but
+    /// consistent and reproducible, time will be used if left unset.
     pub fn with_start_time(mut self, start_time: DateTime<Utc>) -> Self {
         self.start_time = start_time;
         self
     }
 
     /// Set the course's sport
     ///
-    /// Defaults to Cycling if unset.
+    /// Defaults to `cycling` if unset.
     pub fn with_sport(mut self, sport: Sport) -> Self {
         self.sport = sport;
         self
@@ -798,17 +798,17 @@ impl FitCourseOptions {
 
     /// Set the software version to encode
     ///
-    /// This goes in the `file_creator` message's `software_version` field.
-    /// Zero by default.
+    /// This goes in the `file_creator` message's `software_version` field. Zero
+    /// by default.
     pub fn with_software_version(mut self, software_version: u16) -> Self {
         self.software_version = software_version;
         self
     }
 
-    /// Set the software version to encode
+    /// Set the hardware version to encode
     ///
-    /// This goes in the `file_creator` message's `software_version` field.
-    /// Zero by default.
+    /// This goes in the `file_creator` message's `hardware_version` field. Zero
+    /// by default.
     pub fn with_hardware_version(mut self, hardware_version: u8) -> Self {
         self.hardware_version = hardware_version;
         self

src/fit.rs

@@ -42,9 +42,7 @@
 //!
 //! - `full-geolib` causes cxx_build to build all GeographicLib sources instead
 //!   of a hand-picked subset.  This is mainly useful when experimenting with
-//!   new FFI additions, otherwise it simply slows the build down.  This is just
-//!   for convenience when hacking on this crate and experimenting with adding
-//!   new FFIs, and would merely increase build time if enabled on main.
+//!   new FFI additions, otherwise it simply slows the build down.
 
 mod algorithm;
 pub mod course;