Add docs back into the Loft API docs

docs/kcl/loft.md

@@ -18,10 +18,12 @@ loft(sketches: [Sketch], v_degree: NonZeroU32, bez_approximate_rational: bool, b
 | Name | Type | Description | Required |
 |----------|------|-------------|----------|
 | `sketches` | [`[Sketch]`](/docs/kcl/types/Sketch) |  | Yes |
-| `v_degree` | `NonZeroU32` |  | Yes |
-| `bez_approximate_rational` | `bool` |  | Yes |
-| `base_curve_index` | `u32` |  | No |
-| `tolerance` | `number` |  | No |
+| `v_degree` | `NonZeroU32` | Degree of the interpolation. Must be greater than zero.
+        For example, use 2 for quadratic, or 3 for cubic interpolation in the V direction.
+        This defaults to 2, if not specified. | Yes |
+| `bez_approximate_rational` | `bool` | Attempt to approximate rational curves (such as arcs) using a bezier. This will remove banding around interpolations between arcs and non-arcs. It may produce errors in other scenarios Over time, this field won't be necessary. | Yes |
+| `base_curve_index` | `u32` | This can be set to override the automatically determined topological base curve, which is usually the first section encountered. | No |
+| `tolerance` | `number` | Tolerance for the loft operation. | No |
 
 ### Returns
 

docs/kcl/std.json

@@ -95756,6 +95756,7 @@
           }
         },
         "required": true,
+        "description": "Degree of the interpolation. Must be greater than zero.\n        For example, use 2 for quadratic, or 3 for cubic interpolation in the V direction.\n        This defaults to 2, if not specified.",
         "labelRequired": true
       },
       {
@@ -97075,6 +97076,7 @@
           }
         },
         "required": true,
+        "description": "Attempt to approximate rational curves (such as arcs) using a bezier. This will remove banding around interpolations between arcs and non-arcs. It may produce errors in other scenarios Over time, this field won't be necessary.",
         "labelRequired": true
       },
       {
@@ -98397,6 +98399,7 @@
           }
         },
         "required": false,
+        "description": "This can be set to override the automatically determined topological base curve, which is usually the first section encountered.",
         "labelRequired": true
       },
       {
@@ -99718,6 +99721,7 @@
           }
         },
         "required": false,
+        "description": "Tolerance for the loft operation.",
         "labelRequired": true
       }
     ],

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,11 @@ 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 {
+            quote! { String::new() }
+        };
         let label_required = !(i == 0 && metadata.unlabeled_first);
         if ty_string != "ExecState" && ty_string != "Args" {
             let schema = quote! {
@@ -294,6 +305,7 @@ fn do_stdlib_inner(
                     schema: #schema,
                     required: #required,
                     label_required: #label_required,
+                    description: #description.to_string(),
                 }
             });
         }
@@ -355,6 +367,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(),
         }]
     }
 
@@ -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(),
         }]
     }
 
@@ -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(),
         }]
     }
 
@@ -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(),
         }]
     }
 
@@ -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(),
         }]
     }
 
@@ -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,13 +131,15 @@ impl crate::docs::StdLibFn for LineTo {
                 schema: generator.root_schema_for::<LineToData>(),
                 required: true,
                 label_required: true,
+                description: String::new(),
             },
             crate::docs::StdLibFnArg {
                 name: "sketch".to_string(),
                 type_: "Sketch".to_string(),
                 schema: generator.root_schema_for::<Sketch>(),
                 required: true,
                 label_required: true,
+                description: "the sketch you're adding the line to",
             },
         ]
     }
@@ -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(),
         }]
     }
 
@@ -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(),
         }]
     }
 
@@ -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(),
         }]
     }
 
@@ -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(),
         }]
     }
 
@@ -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(),
         }]
     }
 
@@ -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(),
         }]
     }
 
@@ -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(),
         })
     }
 

src/wasm-lib/kcl/src/docs/mod.rs

@@ -57,6 +57,12 @@ pub struct StdLibFnArg {
     pub schema: schemars::schema::RootSchema,
     /// If the argument is required.
     pub required: bool,
+    /// Additional information that could be used instead of the type's description.
+    /// This is helpful if the type is really basic, like "u32" -- that won't tell the user much about
+    /// how this argument is meant to be used.
+    /// Empty string means this has no docs.
+    #[serde(default, skip_serializing_if = "String::is_empty")]
+    pub description: String,
     /// Even in functions that use keyword arguments, not every parameter requires a label (most do though).
     /// Some functions allow one unlabeled parameter, which has to be first in the
     /// argument list.
@@ -104,6 +110,11 @@ impl StdLibFnArg {
     }
 
     pub fn description(&self) -> Option<String> {
+        // Check if we explicitly gave this stdlib arg a description.
+        if !self.description.is_empty() {
+            return Some(self.description.clone());
+        }
+        // If not, then try to get something meaningful from the schema.
         get_description_string_from_schema(&self.schema.clone())
     }
 }

src/wasm-lib/kcl/src/std/loft.rs

@@ -18,9 +18,6 @@ const DEFAULT_V_DEGREE: u32 = 2;
 /// Create a 3D surface or solid by interpolating between two or more sketches.
 pub async fn loft(exec_state: &mut ExecState, args: Args) -> Result<KclValue, KclError> {
     let sketches = args.get_unlabeled_kw_arg("sketches")?;
-    // Degree of the interpolation. Must be greater than zero.
-    // For example, use 2 for quadratic, or 3 for cubic interpolation in the V direction.
-    // This defaults to 2, if not specified.
     let v_degree: NonZeroU32 = args
         .get_kw_arg_opt("vDegree")
         .unwrap_or(NonZeroU32::new(DEFAULT_V_DEGREE).unwrap());
@@ -116,6 +113,14 @@ pub async fn loft(exec_state: &mut ExecState, args: Args) -> Result<KclValue, Kc
     name = "loft",
     keywords = true,
     unlabeled_first = true,
+    arg_docs = {
+        v_degree = "Degree of the interpolation. Must be greater than zero.
+        For example, use 2 for quadratic, or 3 for cubic interpolation in the V direction.
+        This defaults to 2, if not specified.",
+        bez_approximate_rational = "Attempt to approximate rational curves (such as arcs) using a bezier. This will remove banding around interpolations between arcs and non-arcs. It may produce errors in other scenarios Over time, this field won't be necessary.",
+        base_curve_index = "This can be set to override the automatically determined topological base curve, which is usually the first section encountered.",
+        tolerance = "Tolerance for the loft operation.",
+    }
 }]
 async fn inner_loft(
     sketches: Vec<Sketch>,