Automatic C documentation for Duration type: structs, function parameters, and return values (#50)

* document the time unit in structs. emit any default values for durations in the correct unit

* document the unit of durations in function arguments and return values

Author: jadamcrain

generators/c-oo-bindgen/src/lib.rs

@@ -343,15 +343,19 @@ fn write_struct_definition(
                     StructElementType::OneTimeCallback(_) => None,
                     StructElementType::Iterator(_) => None,
                     StructElementType::Collection(_) => None,
-                    StructElementType::Duration(_, default) => {
-                        default.map(|x| format!("{}s", x.as_secs_f32()))
+                    StructElementType::Duration(mapping, default) => {
+                        default.map(|x| mapping.get_value_string(x))
                     }
                 };
 
                 if let Some(default_value) = default_value {
                     f.writeln(&format!("@note Default value is {}", default_value))?;
                 }
 
+                if let StructElementType::Duration(mapping, _) = &element.element_type {
+                    f.writeln(&format!("@note The unit is {}", mapping.unit()))?;
+                }
+
                 Ok(())
             })?;
             f.writeln(&format!(
@@ -591,6 +595,9 @@ fn write_function_docs(
         for param in &handle.parameters {
             f.writeln(&format!("@param {} ", param.name))?;
             docstring_print(f, &param.doc, lib)?;
+            if let Type::Duration(mapping) = param.param_type {
+                f.write(&format!(" ({})", mapping.unit()))?;
+            }
         }
 
         fn write_error_return_doc(f: &mut dyn Printer) -> FormattingResult<()> {
@@ -599,16 +606,22 @@ fn write_function_docs(
 
         match handle.get_type() {
             NativeFunctionType::NoErrorNoReturn => {}
-            NativeFunctionType::NoErrorWithReturn(_, doc) => {
+            NativeFunctionType::NoErrorWithReturn(ret, doc) => {
                 f.writeln("@return ")?;
                 docstring_print(f, &doc, lib)?;
+                if let Type::Duration(mapping) = ret {
+                    f.write(&format!(" ({})", mapping.unit()))?;
+                }
             }
             NativeFunctionType::ErrorNoReturn(_) => {
                 write_error_return_doc(f)?;
             }
-            NativeFunctionType::ErrorWithReturn(_, _, doc) => {
+            NativeFunctionType::ErrorWithReturn(_, ret, doc) => {
                 f.writeln("@param out ")?;
                 docstring_print(f, &doc, lib)?;
+                if let Type::Duration(mapping) = ret {
+                    f.write(&format!(" ({})", mapping.unit()))?;
+                }
                 write_error_return_doc(f)?;
             }
         }

oo-bindgen/src/native_function.rs

@@ -2,6 +2,7 @@ use crate::collection::CollectionHandle;
 use crate::doc::{Doc, DocString};
 use crate::iterator::IteratorHandle;
 use crate::*;
+use std::time::Duration;
 
 #[derive(Debug, Clone, PartialEq)]
 pub enum Type {
@@ -42,6 +43,30 @@ pub enum DurationMapping {
     SecondsFloat,
 }
 
+impl DurationMapping {
+    pub fn unit(&self) -> &'static str {
+        match self {
+            DurationMapping::Milliseconds => "milliseconds",
+            DurationMapping::Seconds => "seconds",
+            DurationMapping::SecondsFloat => "fractional seconds",
+        }
+    }
+
+    pub fn get_value_string(&self, duration: Duration) -> String {
+        match self {
+            DurationMapping::Milliseconds => {
+                format!("{}", duration.as_millis())
+            }
+            DurationMapping::Seconds => {
+                format!("{}", duration.as_secs())
+            }
+            DurationMapping::SecondsFloat => {
+                format!("{}", duration.as_secs_f32())
+            }
+        }
+    }
+}
+
 #[derive(Debug)]
 pub enum ReturnType {
     Void,

tests/foo-schema/src/duration.rs

@@ -8,41 +8,41 @@ pub fn define(lib: &mut LibraryBuilder) -> Result<(), BindingError> {
         .param(
             "value",
             Type::Duration(DurationMapping::Milliseconds),
-            "Duration (in milliseconds)",
+            "Duration",
         )?
         .return_type(ReturnType::new(
             Type::Duration(DurationMapping::Milliseconds),
-            "Duration (in milliseconds)",
+            "Duration",
         ))?
-        .doc("Echo duration through count of milliseconds")?
+        .doc("Echo duration as count of milliseconds")?
         .build()?;
 
     let duration_s_echo_func = lib
         .declare_native_function("duration_s_echo")?
         .param(
             "value",
             Type::Duration(DurationMapping::Seconds),
-            "Duration (in seconds)",
+            "Duration",
         )?
         .return_type(ReturnType::new(
             Type::Duration(DurationMapping::Seconds),
-            "Duration (in seconds)",
+            "Duration",
         ))?
-        .doc("Echo duration through count of seconds")?
+        .doc("Echo duration as count of seconds")?
         .build()?;
 
     let duration_s_float_echo_func = lib
         .declare_native_function("duration_s_float_echo")?
         .param(
             "value",
             Type::Duration(DurationMapping::SecondsFloat),
-            "Duration (in seconds)",
+            "Duration",
         )?
         .return_type(ReturnType::new(
             Type::Duration(DurationMapping::SecondsFloat),
-            "Duration (in seconds)",
+            "Duration",
         ))?
-        .doc("Echo duration through floating point (in seconds)")?
+        .doc("Echo duration as fractional seconds")?
         .build()?;
 
     // Declare static class