Loft uses kw arguments (#4757)

Part of #4600

src/wasm-lib/derive-docs/src/lib.rs

@@ -6,6 +6,8 @@
 mod tests;
 mod unbox;
 
+use std::collections::HashMap;
+
 use convert_case::Casing;
 use inflector::Inflector;
 use once_cell::sync::Lazy;
@@ -47,6 +49,10 @@ struct StdlibMetadata {
     /// If false, all arguments require labels.
     #[serde(default)]
     unlabeled_first: bool,
+
+    /// Key = argument name, value = argument doc.
+    #[serde(default)]
+    arg_docs: HashMap<String, String>,
 }
 
 #[proc_macro_attribute]
@@ -282,6 +288,17 @@ fn do_stdlib_inner(
 
         let ty_string = rust_type_to_openapi_type(&ty_string);
         let required = !ty_ident.to_string().starts_with("Option <");
+        let description = if let Some(s) = metadata.arg_docs.get(&arg_name) {
+            quote! { #s }
+        } else if metadata.keywords && ty_string != "Args" && ty_string != "ExecState" {
+            errors.push(Error::new_spanned(
+                &arg,
+                "Argument was not documented in the arg_docs block",
+            ));
+            continue;
+        } else {
+            quote! { String::new() }
+        };
         let label_required = !(i == 0 && metadata.unlabeled_first);
         if ty_string != "ExecState" && ty_string != "Args" {
             let schema = quote! {
@@ -294,6 +311,7 @@ fn do_stdlib_inner(
                     schema: #schema,
                     required: #required,
                     label_required: #label_required,
+                    description: #description.to_string(),
                 }
             });
         }
@@ -355,6 +373,7 @@ fn do_stdlib_inner(
                 schema,
                 required: true,
                 label_required: true,
+                description: String::new(),
             })
         }
     } else {

src/wasm-lib/derive-docs/src/tests.rs

@@ -116,6 +116,9 @@ fn test_stdlib_line_to() {
     let (item, errors) = do_stdlib(
         quote! {
             name = "lineTo",
+            arg_docs = {
+                sketch = "the sketch you're adding the line to"
+            }
         },
         quote! {
             /// This is some function.

src/wasm-lib/derive-docs/tests/args_with_lifetime.gen

@@ -91,6 +91,7 @@ impl crate::docs::StdLibFn for SomeFn {
             schema: generator.root_schema_for::<Foo>(),
             required: true,
             label_required: true,
+            description: String::new().to_string(),
         }]
     }
 
@@ -105,6 +106,7 @@ impl crate::docs::StdLibFn for SomeFn {
             schema,
             required: true,
             label_required: true,
+            description: String::new(),
         })
     }
 

src/wasm-lib/derive-docs/tests/args_with_refs.gen

@@ -91,6 +91,7 @@ impl crate::docs::StdLibFn for SomeFn {
             schema: generator.root_schema_for::<str>(),
             required: true,
             label_required: true,
+            description: String::new().to_string(),
         }]
     }
 
@@ -105,6 +106,7 @@ impl crate::docs::StdLibFn for SomeFn {
             schema,
             required: true,
             label_required: true,
+            description: String::new(),
         })
     }
 

src/wasm-lib/derive-docs/tests/array.gen

@@ -129,6 +129,7 @@ impl crate::docs::StdLibFn for Show {
             schema: generator.root_schema_for::<[f64; 2usize]>(),
             required: true,
             label_required: true,
+            description: String::new().to_string(),
         }]
     }
 
@@ -143,6 +144,7 @@ impl crate::docs::StdLibFn for Show {
             schema,
             required: true,
             label_required: true,
+            description: String::new(),
         })
     }
 

src/wasm-lib/derive-docs/tests/box.gen

@@ -92,6 +92,7 @@ impl crate::docs::StdLibFn for Show {
             schema: generator.root_schema_for::<f64>(),
             required: true,
             label_required: true,
+            description: String::new().to_string(),
         }]
     }
 
@@ -106,6 +107,7 @@ impl crate::docs::StdLibFn for Show {
             schema,
             required: true,
             label_required: true,
+            description: String::new(),
         })
     }
 

src/wasm-lib/derive-docs/tests/doc_comment_with_code.gen

@@ -130,6 +130,7 @@ impl crate::docs::StdLibFn for MyFunc {
             schema: generator.root_schema_for::<Option<kittycad::types::InputFormat>>(),
             required: false,
             label_required: true,
+            description: String::new().to_string(),
         }]
     }
 
@@ -144,6 +145,7 @@ impl crate::docs::StdLibFn for MyFunc {
             schema,
             required: true,
             label_required: true,
+            description: String::new(),
         })
     }
 

src/wasm-lib/derive-docs/tests/lineTo.gen

@@ -131,6 +131,7 @@ impl crate::docs::StdLibFn for LineTo {
                 schema: generator.root_schema_for::<LineToData>(),
                 required: true,
                 label_required: true,
+                description: String::new().to_string(),
             },
             crate::docs::StdLibFnArg {
                 name: "sketch".to_string(),
@@ -138,6 +139,7 @@ impl crate::docs::StdLibFn for LineTo {
                 schema: generator.root_schema_for::<Sketch>(),
                 required: true,
                 label_required: true,
+                description: "the sketch you're adding the line to".to_string(),
             },
         ]
     }
@@ -153,6 +155,7 @@ impl crate::docs::StdLibFn for LineTo {
             schema,
             required: true,
             label_required: true,
+            description: String::new(),
         })
     }
 

src/wasm-lib/derive-docs/tests/min.gen

@@ -129,6 +129,7 @@ impl crate::docs::StdLibFn for Min {
             schema: generator.root_schema_for::<Vec<f64>>(),
             required: true,
             label_required: true,
+            description: String::new().to_string(),
         }]
     }
 
@@ -143,6 +144,7 @@ impl crate::docs::StdLibFn for Min {
             schema,
             required: true,
             label_required: true,
+            description: String::new(),
         })
     }
 

src/wasm-lib/derive-docs/tests/option.gen

@@ -92,6 +92,7 @@ impl crate::docs::StdLibFn for Show {
             schema: generator.root_schema_for::<Option<f64>>(),
             required: false,
             label_required: true,
+            description: String::new().to_string(),
         }]
     }
 
@@ -106,6 +107,7 @@ impl crate::docs::StdLibFn for Show {
             schema,
             required: true,
             label_required: true,
+            description: String::new(),
         })
     }
 

src/wasm-lib/derive-docs/tests/option_input_format.gen

@@ -92,6 +92,7 @@ impl crate::docs::StdLibFn for Import {
             schema: generator.root_schema_for::<Option<kittycad::types::InputFormat>>(),
             required: false,
             label_required: true,
+            description: String::new().to_string(),
         }]
     }
 
@@ -106,6 +107,7 @@ impl crate::docs::StdLibFn for Import {
             schema,
             required: true,
             label_required: true,
+            description: String::new(),
         })
     }
 

src/wasm-lib/derive-docs/tests/return_vec_box_sketch.gen

@@ -92,6 +92,7 @@ impl crate::docs::StdLibFn for Import {
             schema: generator.root_schema_for::<Option<kittycad::types::InputFormat>>(),
             required: false,
             label_required: true,
+            description: String::new().to_string(),
         }]
     }
 
@@ -106,6 +107,7 @@ impl crate::docs::StdLibFn for Import {
             schema,
             required: true,
             label_required: true,
+            description: String::new(),
         })
     }
 

src/wasm-lib/derive-docs/tests/return_vec_sketch.gen

@@ -92,6 +92,7 @@ impl crate::docs::StdLibFn for Import {
             schema: generator.root_schema_for::<Option<kittycad::types::InputFormat>>(),
             required: false,
             label_required: true,
+            description: String::new().to_string(),
         }]
     }
 
@@ -106,6 +107,7 @@ impl crate::docs::StdLibFn for Import {
             schema,
             required: true,
             label_required: true,
+            description: String::new(),
         })
     }
 

src/wasm-lib/derive-docs/tests/show.gen

@@ -92,6 +92,7 @@ impl crate::docs::StdLibFn for Show {
             schema: generator.root_schema_for::<Vec<f64>>(),
             required: true,
             label_required: true,
+            description: String::new().to_string(),
         }]
     }
 
@@ -106,6 +107,7 @@ impl crate::docs::StdLibFn for Show {
             schema,
             required: true,
             label_required: true,
+            description: String::new(),
         })
     }
 

src/wasm-lib/derive-docs/tests/test_args_with_exec_state.gen

@@ -99,6 +99,7 @@ impl crate::docs::StdLibFn for SomeFunction {
             schema,
             required: true,
             label_required: true,
+            description: String::new(),
         })
     }