Merge pull request #141 from AeroRust/docs/document-features

Docs: document features

Cargo.toml

@@ -44,6 +44,7 @@ serde = { version = "1.0", default-features = false, optional = true }
 serde_with = { version = "~3.11", default-features = false, optional = true }
 
 defmt = { version = "0.3", optional = true }
+document-features = { version = "0.2", optional = true }
 
 [dev-dependencies]
 approx = "0.5"
@@ -53,8 +54,11 @@ quickcheck = { version = "1", default-features = false }
 serde_json = "1.0"
 
 [features]
+## Default features: `std` & `all-sentences`
 default = ["std", "all-sentences"]
+## Enable the `std` (standard library) usage
 std = ["nom/std", "chrono/std", "arrayvec/std", "serde?/std", "serde_with?/std"]
+## Enable derives for (De)Serialization with `serde`
 serde = [
     "serde/derive", 
     "serde_with/macros", 
@@ -64,127 +68,153 @@ serde = [
     "arrayvec/serde"
 ]
 
+## Enable derives of `[email protected]` formatting for embedded platforms
 defmt-03 = ["dep:defmt", "heapless/defmt-03"]
 
+## Enable the documentation of features (disabled by default to remove unnecessary to the functionality dependencies)
+features-docs = ["dep:document-features"]
+
+#! ## Sentences features
+## Enable all sentences
 all-sentences = ["GNSS", "waypoint", "maritime", "water", "vendor-specific", "other"]
-# GNSS specific sentences related to the possition or speed relative to the ground
-GNSS = ["APA", "ALM", "GBS", "GGA", "GLL", "GNS", "GSA", "GST", "GSV", "RMC", "VTG"]
 
+#! ### Categorised features
+
+## GNSS specific sentences related to the position or speed relative to the ground
+GNSS = ["APA", "ALM", "GBS", "GGA", "GLL", "GNS", "GSA", "GST", "GSV", "RMC", "VTG"]
+## Waypoint
 waypoint = ["AAM", "BOD", "BWC", "BWW", "WNC", "ZFO", "ZTG"]
+## Maritime
 maritime = ["waypoint", "water", "radar"]
+## Radar
 radar = ["TTM"]
-water = ["DBK", "DPT", "MTW", "VHW"]
+## Water
+water = ["DBK", "DBS", "DPT", "MTW", "VHW"]
+## Vendor-specific messages
 vendor-specific = ["RMZ"]
+## Other
 other = ["HDT", "MDA", "MWV", "TXT", "ZDA"]
 
-# AAM - Waypoint Arrival Alarm
-# feature: waypoint
+#! ### Supported sentences (alphabetically ordered)
+
+## Waypoint Arrival Alarm
+## (feature: `waypoint`)
 AAM = []
 
-# ALM - GPS Almanac Data
-# feature: GNSS
+## GPS Almanac Data
+## (feature: `GNSS`)
 ALM = []
 
-# APA - Autopilot Sentence "A"
-# feature: GNSS
+## Autopilot Sentence "A"
+## (feature: `GNSS`)
 APA = []
 
-# BOD - Bearing - Waypoint to Waypoint
-# feature: waypoint
+## Bearing - Waypoint to Waypoint
+## (feature: `waypoint`)
 BOD = []
 
-# BWC - Bearing & Distance to Waypoint - Great Circle
-# feature: waypoint
+## Bearing & Distance to Waypoint - Great Circle
+## (feature: `waypoint`)
 BWC = []
 
-# BWW - Bearing - Waypoint to Waypoint
-# feature: waypoint
+## Bearing - Waypoint to Waypoint
+## (feature: `waypoint`)
 BWW = []
 
-# DBK - Depth Below Keel
-# feature: water
+## Depth Below Keel
+## (feature: `water`)
 DBK = []
 
-# DPT - Depth of Water
-# feature: water
+## Depth Below Surface
+## (feature: `water`)
+DBS = []
+
+## Depth of Water
+## (feature: `water`)
 DPT = []
 
-# GBS - GPS Satellite Fault Detection
-# feature: GNSS
+## GPS Satellite Fault Detection
+## (feature: `GNSS`)
 GBS = []
 
-# GGA - Global Positioning System Fix Data
-# feature: GNSS
+## * Global Positioning System Fix Data
+## (feature: `GNSS`)
 GGA = []
 
-# GLL - Geographic Position - Latitude/Longitude
-# feature: GNSS
+## * Geographic Position - Latitude/Longitude
+## (feature: `GNSS`)
 GLL = []
 
-# GNS - Fix data
-# feature: GNSS
+## * Fix data
+## (feature: `GNSS`)
 GNS = []
 
-# GSA - GPS DOP and active satellites
-# feature: GNSS
+## * GPS DOP and active satellites
+## (feature: `GNSS`)
 GSA = []
 
-# GST - GPS Pseudorange Noise Statistics
-# feature: GNSS
+## GPS Pseudorange Noise Statistics
+## (feature: `GNSS`)
 GST = []
 
-# GSV - Satellites in view
-# feature: GNSS
+## * Satellites in view
+## (feature: `GNSS`)
 GSV = []
 
-# HDT - Heading - True
+## Heading - True
+## (feature: `other`)
 HDT = []
 
-# MDA - Meterological Composite
+## Meterological Composite
+## (feature: `other`)
 MDA = []
 
-# MTW - Mean Temperature of Water
-# feature: water
+## Mean Temperature of Water
+## (feature: `water`)
 MTW = []
 
-# MWV - Wind Speed and Angle
+## Wind Speed and Angle
+## (feature: `other`)
 MWV = []
 
-# RMC - Recommended Minimum Navigation Information
-# feature: GNSS
+## * Recommended Minimum Navigation Information
+## (feature: `GNSS`)
 RMC = []
 
-# PGRMZ - Garmin Altitude (Vendor specific)
-# feature: vendor-specific
+## PGRMZ - Garmin Altitude (Vendor specific)
+## (feature: `vendor-specific`)
 RMZ = []
 
-# TTM - Tracked target message
+## Tracked target message
+## (feature: `radar`)
 TTM = []
 
-# TXT - Text message
+## * Text message
+## (feature: `other`)
 TXT = []
 
-# VHW - Water speed and heading
-# feature: water
+## Water speed and heading
+## (feature: `water`)
 VHW = []
 
-# VTG - Track made good and Ground speed
-# feature: GNSS
+## * Track made good and Ground speed
+## (feature: `GNSS`)
 VTG = []
 
-# WNC - Distance - Waypoint to waypoint
-# feature: waypoint
+## Distance - Waypoint to waypoint
+## (feature: `waypoint`)
 WNC = []
 
-# ZDA - Time & Date - UTC, day, month, year and local time zone
+## Time & Date - UTC, day, month, year and local time zone
+## (feature: `other`)
 ZDA = []
 
-# ZFO - UTC & Time from origin Waypoint
-# feature: waypoint
+## UTC & Time from origin Waypoint
+## (feature: `waypoint`)
 ZFO = []
 
-# ZTG - UTC & Time to Destination Waypoint
-# feature: waypoint
+## UTC & Time to Destination Waypoint
+## (feature: `waypoint`)
 ZTG = []
 
 [[test]]

README.md

@@ -6,48 +6,41 @@
 
 [Complete documentation can be found on www.docs.rs/nmea][doc]
 
-## NMEA 0183 sentence parser for Rust.
-
-Supported sentences:
-
-NMEA Standard Sentences
-
-- AAM
-- ALM
-- APA
-- BOD
-- BWC
-- BWW
-- DBK
-- DBS
-- DPT
-- GBS
-- GGA \*
-- GLL \*
-- GNS \*
-- GSA \*
-- GST
-- GSV \*
-- HDT
-- MDA
-- MTW
-- MWV
-- RMC \*
-- TTM
-- VHW
-- VTG \*
-- WNC
-- ZDA
-- ZFO
-- ZTG
-
-Other Sentences
-
-- TXT \*
-
-Vendor Extensions
-
-- PGRMZ
+## NMEA 0183 sentence parser
+
+Supported sentences (alphabetically ordered):
+
+
+- `AAM` - Waypoint Arrival Alarm (feature: `waypoint`)
+- `ALM` - GPS Almanac Data (feature: `GNSS`)
+- `APA` - Autopilot Sentence "A" (feature: `GNSS`)
+- `BOD` - Bearing - Waypoint to Waypoint (feature: `waypoint`)
+- `BWC` - Bearing & Distance to Waypoint - Great Circle (feature: `waypoint`)
+- `BWW` - Bearing - Waypoint to Waypoint (feature: `waypoint`)
+- `DBK` - Depth Below Keel (feature: `water`)
+- `DBS` - Depth Below Surface (feature: `water`)
+- `DPT` - Depth of Water (feature: `water`)
+- `GBS` - GPS Satellite Fault Detection (feature: `GNSS`)
+- `GGA` - * Global Positioning System Fix Data (feature: `GNSS`)
+- `GLL` - * Geographic Position - Latitude/Longitude (feature: `GNSS`)
+- `GNS` - * Fix data (feature: `GNSS`)
+- `GSA` - * GPS DOP and active satellites (feature: `GNSS`)
+- `GST` - GPS Pseudorange Noise Statistics (feature: `GNSS`)
+- `GSV` - * Satellites in view (feature: `GNSS`)
+- `HDT` - Heading - True (feature: `other`)
+- `MDA` - Meterological Composite (feature: `other`)
+- `MTW` - Mean Temperature of Water (feature: `water`)
+- `MWV` - Wind Speed and Angle (feature: `other`)
+- `RMC` - * Recommended Minimum Navigation Information (feature: `GNSS`)
+- `RMZ` - PGRMZ - Garmin Altitude (feature: `vendor-specific`)
+- `TTM` - Tracked target message (feature: `radar`)
+- `TXT` - * Text message (feature: `other`)
+- `VHW` - Water speed and heading (feature: `water`)
+- `VTG` - * Track made good and Ground speed (feature: `GNSS`)
+- `WNC` - Distance - Waypoint to waypoint (feature: `waypoint`)
+- `ZDA` - Time & Date - UTC, day, month, year and local time zone (feature: `other`)
+- `ZFO` - UTC & Time from origin Waypoint (feature: `waypoint`)
+- `ZTG` - UTC & Time to Destination Waypoint (feature: `waypoint`)
 
 **\* [`Nmea::parse()`] supported sentences**
 
@@ -59,10 +52,19 @@ We have an ongoing effort to support as many sentences from `NMEA 0183` as possi
 starting with the most well-known.
 If you'd like to contribute by writing a parser for a given message, check out the [Supporting additional sentences (AeroRust/nmea#54)](https://github.com/AeroRust/nmea/issues/54) issue and contribute in **3** easy steps:
 
-1. Write a comment - Please write a comment in the issue for the sentence(s) you'd like to implement, you will be mentioned on the task to avoid duplicate implementations.
-2. Implement each sentence alongside at least 1 test in its own module under the [`./src/sentences`](./src/sentences) directory using the `nom` crate.
+1. Write a comment in the issue for the sentence(s) you'd like to implement, you will be mentioned on the task to avoid duplicate efforts.
+2. Implement each sentence in it's own branch alongside:
+   - At least **2 tests** (**1 passing** and **1 failing**) in its own module under the [`./src/sentences`](./src/sentences) directory using the `nom` crate.
+   - Re-export the structures and parsing function in [`./src/sentences.rs`](./src/sentences.rs) 
+   - Add a **passing** test to [`tests/all_supported_messages.rs`](./tests/all_supported_messages.rs)
+   - Add the sentence to the features list in `Cargo.toml` in **alphabetical order** and assign it to proper category (if you are unsure which category to use, open a PR to discuss it)
+   - Add the sentence to the `README.md` list of [supported sentences above](./README.md#nmea-0183-sentence-parser-for-rust)
+   - Passing linters checks. Just run `cargo fmt` and fix any issues raised by `cargo clippy`
+   - Appropriate documentation following the rest of the sentences format. For proper documentation you can take a look at `GSV`, `APA` and `WNC` sentences.
 3. Open a PR 🎉
 
+**NB:** We use [https://gpsd.gitlab.io/gpsd/NMEA.html](https://gpsd.gitlab.io/gpsd/NMEA.html) as a reference for most sentences as it's a very well documented project.
+
 ## What is NMEA 0183?
 
 > NMEA 0183 is a combined electrical and data specification for communication