From a4f5d5ae4c684b2e32ffef9361c86d06e1e6c5b7 Mon Sep 17 00:00:00 2001
From: Kurt Wolf <kurtwolfbuilds@gmail.com>
Date: Wed, 13 Dec 2023 21:17:40 -0500
Subject: [PATCH] better docs; fix #18 authentication conditionals

---
 libninja/Cargo.toml          |  6 +++---
 libninja/src/rust.rs         |  9 ++++++++-
 libninja/src/rust/client.rs  | 12 ++++++------
 libninja/src/rust/request.rs |  7 +++++--
 4 files changed, 22 insertions(+), 12 deletions(-)

diff --git a/libninja/Cargo.toml b/libninja/Cargo.toml
index db62011..272623c 100644
--- a/libninja/Cargo.toml
+++ b/libninja/Cargo.toml
@@ -22,7 +22,7 @@ serde_json = "1.0.100"
 serde_yaml = "0.9.22"
 syn = "2.0"
 tokio = { version = "1.29.1", features = ["full"] }
-openapiv3-extended = { version = "3.1" , features = ["v2"] }
+openapiv3-extended = { version = "3.1", features = ["v2"] }
 convert_case = "0.6.0"
 prettyplease = "0.2"
 clap = { version = "4.4.10", features = ["derive"] }
@@ -30,7 +30,7 @@ tera = "1.19.0"
 include_dir = "0.7.3"
 regex = "1.9.0"
 indoc = "2.0.2"
-cargo_toml = "0.17.1"
+cargo_toml = { git = "https://github.com/kurtbuilds/cargo_toml" }
 toml = "0.8.8"
 topo_sort = "0.4.0"
 url = "2.4.0"
@@ -44,7 +44,7 @@ ln-macro = { path = "../macro" }
 ln-core = { path = "../core" }
 libninja_mir = { path = "../mir" }
 libninja_hir = { path = "../hir" }
-libninja_commercial = { path = "../commercial" , optional = true }
+libninja_commercial = { path = "../commercial", optional = true }
 ignore = "0.4.21"
 text_io = "0.1.12"
 
diff --git a/libninja/src/rust.rs b/libninja/src/rust.rs
index 303bdb5..b2ed653 100644
--- a/libninja/src/rust.rs
+++ b/libninja/src/rust.rs
@@ -267,6 +267,12 @@ fn write_request_module(spec: &HirSpec, opts: &PackageConfig) -> Result<()> {
     let mut imports = vec![];
     fs::create_dir_all(src_path.join("request"))?;
     let mut modules = vec![];
+
+    let authenticate = spec.has_security()
+        .then(|| quote! {
+                r = self.client.authenticate(r);
+            }).unwrap_or_default();
+
     for operation in &spec.operations {
         let fname = operation.file_name();
         let request_structs = build_request_struct(operation, spec, &opts);
@@ -284,6 +290,7 @@ fn write_request_module(spec: &HirSpec, opts: &PackageConfig) -> Result<()> {
         let builder_methods = builder_methods
             .into_iter()
             .map(|s| codegen_function(s, quote! { mut self , }));
+
         let file = quote! {
             use crate::#client_name;
             #(#request_structs)*
@@ -301,7 +308,7 @@ fn write_request_module(spec: &HirSpec, opts: &PackageConfig) -> Result<()> {
                         let url = #url;
                         let mut r = self.client.client.#method(url);
                         r = r.set_query(self.params);
-                        r = self.client.authenticate(r);
+                        #authenticate
                         let res = r.await?;
                         res.json().map_err(Into::into)
                     })
diff --git a/libninja/src/rust/client.rs b/libninja/src/rust/client.rs
index ab37f4a..7c27614 100644
--- a/libninja/src/rust/client.rs
+++ b/libninja/src/rust/client.rs
@@ -193,8 +193,8 @@ pub fn authenticate_variant(
     }
 }
 
-pub fn build_Client_authenticate(mir_spec: &HirSpec, opt: &PackageConfig) -> TokenStream {
-    let authenticate_variant = mir_spec.security
+pub fn build_Client_authenticate(spec: &HirSpec, opt: &PackageConfig) -> TokenStream {
+    let authenticate_variant = spec.security
         .iter()
         .map(|req| authenticate_variant(req, opt))
         .collect::<Vec<_>>();
@@ -235,14 +235,14 @@ fn build_new_fn(security: bool, opt: &PackageConfig) -> TokenStream {
     }
 }
 
-pub fn impl_Client(mir_spec: &HirSpec, opt: &PackageConfig) -> TokenStream {
+pub fn impl_Client(spec: &HirSpec, opt: &PackageConfig) -> TokenStream {
     let client_struct_name = opt.client_name().to_rust_struct();
-    let path_fns = impl_ServiceClient_paths(mir_spec);
+    let path_fns = impl_ServiceClient_paths(spec);
 
-    let security = mir_spec.has_security();
+    let security = spec.has_security();
     let new_fn = build_new_fn(security, opt);
     let authenticate = if security {
-        build_Client_authenticate(mir_spec, opt)
+        build_Client_authenticate(spec, opt)
     } else {
         TokenStream::new()
     };
diff --git a/libninja/src/rust/request.rs b/libninja/src/rust/request.rs
index 7abec2b..b305ef8 100644
--- a/libninja/src/rust/request.rs
+++ b/libninja/src/rust/request.rs
@@ -248,9 +248,12 @@ pub fn build_request_struct(
     // let mut instance_methods = vec![build_send_function(operation, spec)];
     // let mut_self_instance_methods = build_request_struct_builder_methods(operation);
 
-    let doc = doc("Create this with the associated client method.
+    let fn_name = operation.name.to_rust_ident().0;
+    let response = operation.ret.to_rust_type().to_string().replace(" ", "");
+    let client = opt.client_name().to_rust_struct().to_string().replace(" ", "");
+    let doc = Some(Doc(format!(r#"You should use this struct via [`{client}::{fn_name}`].
 
-That method takes required values as arguments. Set optional values using builder methods on this struct.");
+On request success, this will return a [`{response}`]."#, )));
     let mut result = vec![Class {
         name: operation.request_struct_name().to_rust_struct(),
         doc,