update the docs

- document all public modules
- close #44
- bump version to v0.1.0-pre.9

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "hap"
-version = "0.1.0-pre.8"
+version = "0.1.0-pre.9"
 authors = ["Elias Wilken <[email protected]>"]
 edition = "2018"
 description = "Rust implementation of the Apple HomeKit Accessory Protocol (HAP)"

codegen/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "hap-codegen"
-version = "0.1.0-pre.8"
+version = "0.1.0-pre.9"
 authors = ["Elias Wilken <[email protected]>"]
 edition = "2018"
 description = "Rust implementation of the Apple HomeKit Accessory Protocol (HAP)"

codegen/src/main.rs

@@ -710,7 +710,7 @@ fn pascal_case_helper(
 static CATEGORIES: &'static str = "// this file is auto-generated by hap-codegen\n
 use serde::{Deserialize, Serialize};
 
-/// HAP Accessory category.
+/// HAP accessory category.
 #[derive(Debug, Copy, Clone, Serialize, Deserialize)]
 pub enum AccessoryCategory {
 {{#each sorted_categories as |c|}}\
@@ -728,7 +728,7 @@ use std::str::FromStr;
 
 use crate::Error;
 
-/// HAP Service and Characteristic type representation.
+/// HAP service and characteristic type representation.
 #[derive(Debug, Copy, Clone, Eq, PartialEq, Hash)]
 pub enum HapType {
     Unknown,
@@ -820,12 +820,12 @@ use crate::{
 };
 
 // TODO - re-check MaximumDataLength
-/// {{characteristic.DefaultDescription}} Characteristic.
+/// {{characteristic.DefaultDescription}} characteristic.
 #[derive(Debug, Default, Serialize)]
 pub struct {{pascal_case characteristic.DefaultDescription}}Characteristic(Characteristic<{{type characteristic.Format}}>);
 {{#if in_values includeZero=true}}{{in_values_enum in_values}}{{/if}}{{#if out_values includeZero=true}}{{out_values_enum out_values}}{{/if}}
 impl {{pascal_case characteristic.DefaultDescription}}Characteristic {
-    /// Creates a new {{characteristic.DefaultDescription}} Characteristic.
+    /// Creates a new {{characteristic.DefaultDescription}} characteristic.
     pub fn new(id: u64, accessory_id: u64) -> Self {
         #[allow(unused_mut)]
         let mut c = Self(Characteristic::<{{type characteristic.Format}}> {
@@ -926,7 +926,7 @@ impl AsyncCharacteristicCallbacks<{{type characteristic.Format}}> for {{pascal_c
 ";
 
 static CHARACTERISTIC_MOD: &'static str = "// this file is auto-generated by hap-codegen
-{{#each characteristics as |c|}}\npub mod {{c}};{{/each}}
+{{#each characteristics as |c|}}\n/// {{c.name}} characteristic definition.\npub mod {{c.file_name}};{{/each}}
 ";
 
 static SERVICE: &'static str = "// this file is auto-generated by hap-codegen\n
@@ -946,12 +946,12 @@ use crate::{
     HapType,
 };
 
-/// {{service.DefaultDescription}} Service.
+/// {{service.DefaultDescription}} service.
 #[derive(Debug, Default)]
 pub struct {{pascal_case service.DefaultDescription}}Service {
-    /// Instance ID of the {{service.DefaultDescription}} Service.
+    /// Instance ID of the {{service.DefaultDescription}} service.
     id: u64,
-    /// `HapType` of the {{service.DefaultDescription}} Service.
+    /// [`HapType`](HapType) of the {{service.DefaultDescription}} service.
     hap_type: HapType,
     /// When set to true, this service is not visible to user.
     hidden: bool,
@@ -961,17 +961,17 @@ pub struct {{pascal_case service.DefaultDescription}}Service {
     linked_services: Vec<u64>,
 
 {{#each required_characteristics as |r|}}\
-\t/// {{r.DefaultDescription}} Characteristic (required).
+\t/// {{r.DefaultDescription}} characteristic (required).
 \tpub {{snake_case r.DefaultDescription}}: {{pascal_case r.DefaultDescription}}Characteristic,
 {{/each}}\
 \n{{#each optional_characteristics as |o|}}\
-\t/// {{o.DefaultDescription}} Characteristic (optional).
+\t/// {{o.DefaultDescription}} characteristic (optional).
 \tpub {{snake_case o.DefaultDescription}}: Option<{{pascal_case o.DefaultDescription}}Characteristic>,
 {{/each}}\
 }
 
 impl {{pascal_case service.DefaultDescription}}Service {
-    /// Creates a new {{service.DefaultDescription}} Service.
+    /// Creates a new {{service.DefaultDescription}} service.
     pub fn new(id: u64, accessory_id: u64) -> Self {
         Self {
             id,
@@ -1084,7 +1084,7 @@ impl Serialize for {{pascal_case service.DefaultDescription}}Service {
 ";
 
 static SERVICE_MOD: &'static str = "// this file is auto-generated by hap-codegen
-{{#each services as |s|}}\npub mod {{s}};{{/each}}
+{{#each services as |s|}}\n/// {{s.name}} service definition.\npub mod {{s.file_name}};{{/each}}
 ";
 
 static ACCESSORY: &'static str = "// this file is auto-generated by hap-codegen\n
@@ -1097,20 +1097,20 @@ use crate::{
 \tResult,
 };
 
-/// {{service.DefaultDescription}} Accessory.
+/// {{service.DefaultDescription}} accessory.
 #[derive(Debug, Default)]
 pub struct {{pascal_case service.DefaultDescription}}Accessory {
     /// ID of the {{service.DefaultDescription}} Accessory.
     id: u64,
 
-    /// Accessory Information Service.
+    /// Accessory Information service.
     pub accessory_information: AccessoryInformationService,
-    /// {{service.DefaultDescription}} Service.
+    /// {{service.DefaultDescription}} service.
     pub {{snake_case service.DefaultDescription}}: {{pascal_case service.DefaultDescription}}Service,
 }
 
 impl {{pascal_case service.DefaultDescription}}Accessory {
-    /// Creates a new {{service.DefaultDescription}} Accessory.
+    /// Creates a new {{service.DefaultDescription}} accessory.
     pub fn new(id: u64, information: AccessoryInformation) -> Result<Self> {
         let accessory_information = information.to_service(1, id)?;
         let {{snake_case service.DefaultDescription}}_id = accessory_information.get_characteristics().len() as u64;
@@ -1178,7 +1178,7 @@ impl Serialize for {{pascal_case service.DefaultDescription}}Accessory {
 ";
 
 static ACCESSORY_MOD: &'static str = "// this file is auto-generated by hap-codegen
-{{#each accessories as |a|}}\npub mod {{a}};{{/each}}
+{{#each accessories as |a|}}\n/// {{a.name}} accessory definition.\npub mod {{a.file_name}};{{/each}}
 ";
 
 static EXAMPLE: &'static str = "\
@@ -1378,9 +1378,15 @@ fn main() {
         characteristic_path.push_str(".rs");
         let mut characteristic_file = File::create(&characteristic_path).unwrap();
         characteristic_file.write_all(characteristic.as_bytes()).unwrap();
-        characteristic_names.push(characteristic_file_name);
+        characteristic_names.push(json!({ "name": c.name, "file_name": characteristic_file_name }));
     }
-    characteristic_names.sort();
+    characteristic_names.sort_by(|a, b| {
+        a.get("file_name")
+            .unwrap()
+            .as_str()
+            .unwrap()
+            .cmp(&b.get("file_name").unwrap().as_str().unwrap())
+    });
     let characteristic_mod = handlebars
         .render(
             "characteristic_mod",
@@ -1450,7 +1456,7 @@ fn main() {
         let mut service_file = File::create(&service_path).unwrap();
         service_file.write_all(service.as_bytes()).unwrap();
 
-        service_names.push(service_file_name.clone());
+        service_names.push(json!({ "name": s.name.clone(), "file_name": service_file_name.clone() }));
 
         if !NON_IDIOMATIC_SERVICES.contains(&s.name.to_lowercase().as_str()) {
             let accessory = handlebars
@@ -1474,7 +1480,7 @@ fn main() {
                 example_file.write_all(example.as_bytes()).unwrap();
             }
 
-            accessory_names.push(service_file_name);
+            accessory_names.push(json!({ "name": s.name.clone(), "file_name": service_file_name }));
         }
     }
     let service_mod = handlebars

src/accessory/category.rs

@@ -2,7 +2,7 @@
 
 use serde::{Deserialize, Serialize};
 
-/// HAP Accessory category.
+/// HAP accessory category.
 #[derive(Debug, Copy, Clone, Serialize, Deserialize)]
 pub enum AccessoryCategory {
 	Other = 1,

src/accessory/defined/mod.rs

@@ -1,8 +1,16 @@
+/// Bridge accessory definition.
 pub mod bridge;
+/// Faucet accessory definition.
 pub mod faucet;
+/// Heater-Cooler accessory definition.
 pub mod heater_cooler;
+/// Irrigation-System accessory definition.
 pub mod irrigation_system;
+/// Lightbulb accessory definition.
 pub mod lightbulb;
+/// Lock accessory definition.
 pub mod lock;
+/// Shower Head accessory definition.
 pub mod shower_head;
+/// Television accessory definition.
 pub mod television;

src/accessory/generated/air_purifier.rs

@@ -9,20 +9,20 @@ use crate::{
 	Result,
 };
 
-/// Air Purifier Accessory.
+/// Air Purifier accessory.
 #[derive(Debug, Default)]
 pub struct AirPurifierAccessory {
     /// ID of the Air Purifier Accessory.
     id: u64,
 
-    /// Accessory Information Service.
+    /// Accessory Information service.
     pub accessory_information: AccessoryInformationService,
-    /// Air Purifier Service.
+    /// Air Purifier service.
     pub air_purifier: AirPurifierService,
 }
 
 impl AirPurifierAccessory {
-    /// Creates a new Air Purifier Accessory.
+    /// Creates a new Air Purifier accessory.
     pub fn new(id: u64, information: AccessoryInformation) -> Result<Self> {
         let accessory_information = information.to_service(1, id)?;
         let air_purifier_id = accessory_information.get_characteristics().len() as u64;

src/accessory/generated/air_quality_sensor.rs

@@ -9,20 +9,20 @@ use crate::{
 	Result,
 };
 
-/// Air Quality Sensor Accessory.
+/// Air Quality Sensor accessory.
 #[derive(Debug, Default)]
 pub struct AirQualitySensorAccessory {
     /// ID of the Air Quality Sensor Accessory.
     id: u64,
 
-    /// Accessory Information Service.
+    /// Accessory Information service.
     pub accessory_information: AccessoryInformationService,
-    /// Air Quality Sensor Service.
+    /// Air Quality Sensor service.
     pub air_quality_sensor: AirQualitySensorService,
 }
 
 impl AirQualitySensorAccessory {
-    /// Creates a new Air Quality Sensor Accessory.
+    /// Creates a new Air Quality Sensor accessory.
     pub fn new(id: u64, information: AccessoryInformation) -> Result<Self> {
         let accessory_information = information.to_service(1, id)?;
         let air_quality_sensor_id = accessory_information.get_characteristics().len() as u64;

src/accessory/generated/carbon_dioxide_sensor.rs

@@ -9,20 +9,20 @@ use crate::{
 	Result,
 };
 
-/// Carbon dioxide Sensor Accessory.
+/// Carbon dioxide Sensor accessory.
 #[derive(Debug, Default)]
 pub struct CarbonDioxideSensorAccessory {
     /// ID of the Carbon dioxide Sensor Accessory.
     id: u64,
 
-    /// Accessory Information Service.
+    /// Accessory Information service.
     pub accessory_information: AccessoryInformationService,
-    /// Carbon dioxide Sensor Service.
+    /// Carbon dioxide Sensor service.
     pub carbon_dioxide_sensor: CarbonDioxideSensorService,
 }
 
 impl CarbonDioxideSensorAccessory {
-    /// Creates a new Carbon dioxide Sensor Accessory.
+    /// Creates a new Carbon dioxide Sensor accessory.
     pub fn new(id: u64, information: AccessoryInformation) -> Result<Self> {
         let accessory_information = information.to_service(1, id)?;
         let carbon_dioxide_sensor_id = accessory_information.get_characteristics().len() as u64;

src/accessory/generated/carbon_monoxide_sensor.rs

@@ -9,20 +9,20 @@ use crate::{
 	Result,
 };
 
-/// Carbon monoxide Sensor Accessory.
+/// Carbon monoxide Sensor accessory.
 #[derive(Debug, Default)]
 pub struct CarbonMonoxideSensorAccessory {
     /// ID of the Carbon monoxide Sensor Accessory.
     id: u64,
 
-    /// Accessory Information Service.
+    /// Accessory Information service.
     pub accessory_information: AccessoryInformationService,
-    /// Carbon monoxide Sensor Service.
+    /// Carbon monoxide Sensor service.
     pub carbon_monoxide_sensor: CarbonMonoxideSensorService,
 }
 
 impl CarbonMonoxideSensorAccessory {
-    /// Creates a new Carbon monoxide Sensor Accessory.
+    /// Creates a new Carbon monoxide Sensor accessory.
     pub fn new(id: u64, information: AccessoryInformation) -> Result<Self> {
         let accessory_information = information.to_service(1, id)?;
         let carbon_monoxide_sensor_id = accessory_information.get_characteristics().len() as u64;

src/accessory/generated/contact_sensor.rs

@@ -9,20 +9,20 @@ use crate::{
 	Result,
 };
 
-/// Contact Sensor Accessory.
+/// Contact Sensor accessory.
 #[derive(Debug, Default)]
 pub struct ContactSensorAccessory {
     /// ID of the Contact Sensor Accessory.
     id: u64,
 
-    /// Accessory Information Service.
+    /// Accessory Information service.
     pub accessory_information: AccessoryInformationService,
-    /// Contact Sensor Service.
+    /// Contact Sensor service.
     pub contact_sensor: ContactSensorService,
 }
 
 impl ContactSensorAccessory {
-    /// Creates a new Contact Sensor Accessory.
+    /// Creates a new Contact Sensor accessory.
     pub fn new(id: u64, information: AccessoryInformation) -> Result<Self> {
         let accessory_information = information.to_service(1, id)?;
         let contact_sensor_id = accessory_information.get_characteristics().len() as u64;

src/accessory/generated/door.rs

@@ -9,20 +9,20 @@ use crate::{
 	Result,
 };
 
-/// Door Accessory.
+/// Door accessory.
 #[derive(Debug, Default)]
 pub struct DoorAccessory {
     /// ID of the Door Accessory.
     id: u64,
 
-    /// Accessory Information Service.
+    /// Accessory Information service.
     pub accessory_information: AccessoryInformationService,
-    /// Door Service.
+    /// Door service.
     pub door: DoorService,
 }
 
 impl DoorAccessory {
-    /// Creates a new Door Accessory.
+    /// Creates a new Door accessory.
     pub fn new(id: u64, information: AccessoryInformation) -> Result<Self> {
         let accessory_information = information.to_service(1, id)?;
         let door_id = accessory_information.get_characteristics().len() as u64;

src/accessory/generated/fan.rs

@@ -9,20 +9,20 @@ use crate::{
 	Result,
 };
 
-/// Fan Accessory.
+/// Fan accessory.
 #[derive(Debug, Default)]
 pub struct FanAccessory {
     /// ID of the Fan Accessory.
     id: u64,
 
-    /// Accessory Information Service.
+    /// Accessory Information service.
     pub accessory_information: AccessoryInformationService,
-    /// Fan Service.
+    /// Fan service.
     pub fan: FanService,
 }
 
 impl FanAccessory {
-    /// Creates a new Fan Accessory.
+    /// Creates a new Fan accessory.
     pub fn new(id: u64, information: AccessoryInformation) -> Result<Self> {
         let accessory_information = information.to_service(1, id)?;
         let fan_id = accessory_information.get_characteristics().len() as u64;

src/accessory/generated/fan_v2.rs

@@ -9,20 +9,20 @@ use crate::{
 	Result,
 };
 
-/// Fan v2 Accessory.
+/// Fan v2 accessory.
 #[derive(Debug, Default)]
 pub struct FanV2Accessory {
     /// ID of the Fan v2 Accessory.
     id: u64,
 
-    /// Accessory Information Service.
+    /// Accessory Information service.
     pub accessory_information: AccessoryInformationService,
-    /// Fan v2 Service.
+    /// Fan v2 service.
     pub fan_v2: FanV2Service,
 }
 
 impl FanV2Accessory {
-    /// Creates a new Fan v2 Accessory.
+    /// Creates a new Fan v2 accessory.
     pub fn new(id: u64, information: AccessoryInformation) -> Result<Self> {
         let accessory_information = information.to_service(1, id)?;
         let fan_v2_id = accessory_information.get_characteristics().len() as u64;