add operation summary doc comments (#530)

* add operation summary doc comments

* generate

Co-authored-by: Cameron Taggart <cameron.taggart@gmail.com>

Author: cataggar

services/autorust/codegen/src/codegen.rs

@@ -1,5 +1,9 @@
-use crate::{identifier::ident, spec, Config, PropertyName, ResolvedSchema, Spec};
-use autorust_openapi::{DataType, ReferenceOr, Schema, SchemaCommon};
+use crate::{
+    identifier::ident,
+    spec::{self, TypeName},
+    Config, PropertyName, ResolvedSchema, Spec,
+};
+use autorust_openapi::DataType;
 use heck::CamelCase;
 use once_cell::sync::Lazy;
 use proc_macro2::TokenStream;
@@ -63,10 +67,6 @@ impl CodeGen {
 pub enum Error {
     #[error("SpecError: {0}")]
     Spec(#[from] spec::Error),
-    #[error("ArrayExpectedToHaveItems")]
-    ArrayExpectedToHaveItems,
-    #[error("NoNameForRef")]
-    NoNameForRef,
     #[error("creating function name: {0}")]
     FunctionName(#[source] crate::identifier::Error),
     #[error("creating type name for schema ref: {0}")]
@@ -123,10 +123,6 @@ pub fn is_vec(ts: &TokenStream) -> bool {
     ts.to_string().starts_with("Vec <")
 }
 
-pub fn get_schema_array_items(schema: &SchemaCommon) -> Result<&ReferenceOr<Schema>, Error> {
-    schema.items.as_ref().as_ref().ok_or(Error::ArrayExpectedToHaveItems)
-}
-
 /// A header placed at the top the file to say that it is generated by AutoRust.
 pub fn create_generated_by_header() -> TokenStream {
     let version = env!("CARGO_PKG_VERSION");
@@ -168,106 +164,44 @@ pub fn enum_values_as_strings(values: &[Value]) -> Vec<&str> {
         .collect()
 }
 
-pub enum TypeName {
-    Reference(String),
-    Array(Box<TypeName>),
-    Value,
-    Bytes,
-    Int32,
-    Int64,
-    Float32,
-    Float64,
-    Boolean,
-    String,
-}
-
-impl TypeName {
-    pub fn to_token_stream(&self, as_ref: bool, qualify_models: bool) -> Result<TokenStream, Error> {
-        Ok(match self {
-            TypeName::Reference(name) => {
-                let idt = ident(&name.to_camel_case()).map_err(Error::TypeNameForSchemaRef)?;
-                let idt = if qualify_models {
-                    quote! { models::#idt }
-                } else {
-                    idt
-                };
-                match as_ref {
-                    true => quote! { impl Into<#idt> },
-                    false => idt,
-                }
-            }
-            TypeName::Array(vec_items_typ) => {
-                let vec_items_typ = vec_items_typ.to_token_stream(false, qualify_models)?;
-                match as_ref {
-                    true => quote! { impl Into<Vec<#vec_items_typ>> },
-                    false => quote! { Vec<#vec_items_typ> },
-                }
+pub fn type_name_gen(type_name: &TypeName, as_ref: bool, qualify_models: bool) -> Result<TokenStream, Error> {
+    Ok(match type_name {
+        TypeName::Reference(name) => {
+            let idt = ident(&name.to_camel_case()).map_err(Error::TypeNameForSchemaRef)?;
+            let idt = if qualify_models {
+                quote! { models::#idt }
+            } else {
+                idt
+            };
+            match as_ref {
+                true => quote! { impl Into<#idt> },
+                false => idt,
             }
-            TypeName::Value => match as_ref {
-                true => quote! { impl Into<serde_json::Value> },
-                false => quote! { serde_json::Value },
-            },
-            TypeName::Bytes => match as_ref {
-                true => quote! { impl Into<bytes::Bytes> },
-                false => quote! { bytes::Bytes },
-            },
-            TypeName::Int32 => quote! { i32 },
-            TypeName::Int64 => quote! { i64 },
-            TypeName::Float32 => quote! { f32 },
-            TypeName::Float64 => quote! { f64 },
-            TypeName::Boolean => quote! { bool },
-            TypeName::String => match as_ref {
-                true => quote! { impl Into<String> },
-                false => quote! { String },
-            },
-        })
-    }
-}
-
-pub fn get_type_name_for_schema(schema: &SchemaCommon) -> Result<TypeName, Error> {
-    Ok(if let Some(schema_type) = &schema.type_ {
-        let format = schema.format.as_deref();
-        match schema_type {
-            DataType::Array => {
-                let items = get_schema_array_items(schema)?;
-                let vec_items_typ = get_type_name_for_schema_ref(items)?;
-                TypeName::Array(Box::new(vec_items_typ))
-            }
-            DataType::Integer => {
-                if format == Some("int32") {
-                    TypeName::Int32
-                } else {
-                    TypeName::Int64
-                }
-            }
-            DataType::Number => {
-                if format == Some("float") {
-                    TypeName::Float32
-                } else {
-                    TypeName::Float64
-                }
-            }
-            DataType::String => TypeName::String,
-            DataType::Boolean => TypeName::Boolean,
-            DataType::Object => TypeName::Value,
-            DataType::File => TypeName::Bytes,
         }
-    } else {
-        // eprintln!(
-        //     "WARN unknown type in get_type_name_for_schema, description {:?}",
-        //     schema.description
-        // );
-        TypeName::Value
-    })
-}
-
-pub fn get_type_name_for_schema_ref(schema: &ReferenceOr<Schema>) -> Result<TypeName, Error> {
-    Ok(match schema {
-        ReferenceOr::Reference { reference, .. } => {
-            let name = reference.name.as_ref().ok_or(Error::NoNameForRef)?;
-            TypeName::Reference(name.to_owned())
+        TypeName::Array(vec_items_typ) => {
+            let vec_items_typ = type_name_gen(vec_items_typ, false, qualify_models)?;
+            match as_ref {
+                true => quote! { impl Into<Vec<#vec_items_typ>> },
+                false => quote! { Vec<#vec_items_typ> },
+            }
         }
-        ReferenceOr::Item(schema) => get_type_name_for_schema(&schema.common)?,
+        TypeName::Value => match as_ref {
+            true => quote! { impl Into<serde_json::Value> },
+            false => quote! { serde_json::Value },
+        },
+        TypeName::Bytes => match as_ref {
+            true => quote! { impl Into<bytes::Bytes> },
+            false => quote! { bytes::Bytes },
+        },
+        TypeName::Int32 => quote! { i32 },
+        TypeName::Int64 => quote! { i64 },
+        TypeName::Float32 => quote! { f32 },
+        TypeName::Float64 => quote! { f64 },
+        TypeName::Boolean => quote! { bool },
+        TypeName::String => match as_ref {
+            true => quote! { impl Into<String> },
+            false => quote! { String },
+        },
     })
 }
 

services/autorust/codegen/src/codegen_models.rs

@@ -1,10 +1,11 @@
 use crate::{
     codegen::{
-        add_option, create_generated_by_header, enum_values_as_strings, get_schema_array_items, get_type_name_for_schema,
-        get_type_name_for_schema_ref, is_basic_type, is_local_enum, is_local_struct, is_vec, Error,
+        add_option, create_generated_by_header, enum_values_as_strings, is_basic_type, is_local_enum, is_local_struct, is_vec,
+        type_name_gen, Error,
     },
     identifier::{CamelCaseIdent, SnakeCaseIdent},
-    spec, CodeGen, PropertyName, ResolvedSchema,
+    spec::{self, get_schema_array_items, get_type_name_for_schema, get_type_name_for_schema_ref},
+    CodeGen, PropertyName, ResolvedSchema, Spec,
 };
 use autorust_openapi::{DataType, Reference, SchemaCommon};
 use indexmap::IndexMap;
@@ -20,28 +21,12 @@ fn is_array(schema: &SchemaCommon) -> bool {
     matches!(schema.type_, Some(DataType::Array))
 }
 
-pub fn create_models(cg: &CodeGen) -> Result<TokenStream, Error> {
-    let mut file = TokenStream::new();
-    file.extend(create_generated_by_header());
-
-    let has_case_workaround = cg.should_workaround_case();
-
-    file.extend(quote! {
-        #![allow(non_camel_case_types)]
-        #![allow(unused_imports)]
-        use serde::{Deserialize, Serialize};
-    });
-    if has_case_workaround {
-        file.extend(quote! {
-        use azure_core::util::case_insensitive_deserialize;
-        });
-    }
-
+fn all_schemas(spec: &Spec) -> Result<IndexMap<RefKey, ResolvedSchema>, Error> {
     let mut all_schemas: IndexMap<RefKey, ResolvedSchema> = IndexMap::new();
 
     // all definitions from input_files
-    for (doc_file, doc) in cg.spec.input_docs() {
-        let schemas = cg.spec.resolve_schema_map(doc_file, &doc.definitions).map_err(Error::Spec)?;
+    for (doc_file, doc) in spec.input_docs() {
+        let schemas = spec.resolve_schema_map(doc_file, &doc.definitions).map_err(Error::Spec)?;
         for (name, schema) in schemas {
             all_schemas.insert(
                 RefKey {
@@ -54,14 +39,34 @@ pub fn create_models(cg: &CodeGen) -> Result<TokenStream, Error> {
     }
 
     // any referenced schemas from other files
-    for (doc_file, api) in cg.spec.input_docs() {
+    for (doc_file, api) in spec.input_docs() {
         for reference in openapi::get_api_schema_references(doc_file, api) {
-            add_schema_refs(cg, &mut all_schemas, doc_file, reference)?;
+            add_schema_refs(spec, &mut all_schemas, doc_file, reference)?;
         }
     }
 
+    Ok(all_schemas)
+}
+
+pub fn create_models(cg: &CodeGen) -> Result<TokenStream, Error> {
+    let mut file = TokenStream::new();
+    file.extend(create_generated_by_header());
+
+    let has_case_workaround = cg.should_workaround_case();
+
+    file.extend(quote! {
+        #![allow(non_camel_case_types)]
+        #![allow(unused_imports)]
+        use serde::{Deserialize, Serialize};
+    });
+    if has_case_workaround {
+        file.extend(quote! {
+        use azure_core::util::case_insensitive_deserialize;
+        });
+    }
+
     let mut schema_names = IndexMap::new();
-    for (ref_key, schema) in &all_schemas {
+    for (ref_key, schema) in &all_schemas(&cg.spec)? {
         let doc_file = &ref_key.file_path;
         let schema_name = &ref_key.name;
         if let Some(_first_doc_file) = schema_names.insert(schema_name, doc_file) {
@@ -89,24 +94,24 @@ pub fn create_models(cg: &CodeGen) -> Result<TokenStream, Error> {
 
 fn create_basic_type_alias(property_name: &str, property: &ResolvedSchema) -> Result<(TokenStream, TokenStream), Error> {
     let id = property_name.to_camel_case_ident().map_err(Error::StructName)?;
-    let value = get_type_name_for_schema(&property.schema.common)?.to_token_stream(false, false)?;
+    let value = type_name_gen(&get_type_name_for_schema(&property.schema.common)?, false, false)?;
     Ok((id, value))
 }
 
 // For create_models. Recursively adds schema refs.
 fn add_schema_refs(
-    cg: &CodeGen,
+    spec: &Spec,
     schemas: &mut IndexMap<RefKey, ResolvedSchema>,
     doc_file: &Path,
     schema_ref: Reference,
 ) -> Result<(), Error> {
-    let schema = cg.spec.resolve_schema_ref(doc_file, schema_ref)?;
+    let schema = spec.resolve_schema_ref(doc_file, schema_ref)?;
     if let Some(ref_key) = schema.ref_key.clone() {
-        if !schemas.contains_key(&ref_key) && !cg.spec.is_input_file(&ref_key.file_path) {
+        if !schemas.contains_key(&ref_key) && !spec.is_input_file(&ref_key.file_path) {
             let refs = get_schema_schema_references(&schema.schema);
             schemas.insert(ref_key.clone(), schema);
             for reference in refs {
-                add_schema_refs(cg, schemas, &ref_key.file_path, reference)?;
+                add_schema_refs(spec, schemas, &ref_key.file_path, reference)?;
             }
         }
     }
@@ -161,7 +166,7 @@ fn create_enum(
 fn create_vec_alias(alias_name: &str, schema: &ResolvedSchema) -> Result<TokenStream, Error> {
     let items = get_schema_array_items(&schema.schema.common)?;
     let typ = &alias_name.to_camel_case_ident().map_err(Error::VecAliasName)?;
-    let items_typ = get_type_name_for_schema_ref(items)?.to_token_stream(false, false)?;
+    let items_typ = type_name_gen(&get_type_name_for_schema_ref(items)?, false, false)?;
     Ok(quote! { pub type #typ = Vec<#items_typ>; })
 }
 
@@ -175,7 +180,7 @@ fn create_struct(cg: &CodeGen, doc_file: &Path, struct_name: &str, schema: &Reso
     let required: HashSet<&str> = schema.schema.required.iter().map(String::as_str).collect();
 
     for schema in &schema.schema.all_of {
-        let type_name = get_type_name_for_schema_ref(schema)?.to_token_stream(false, false)?;
+        let type_name = type_name_gen(&get_type_name_for_schema_ref(schema)?, false, false)?;
         let field_name = type_name.to_string().to_snake_case_ident().map_err(Error::StructFieldName)?;
         props.extend(quote! {
             #[serde(flatten)]
@@ -289,7 +294,7 @@ fn create_struct_field_type(
                 Ok((tp_name, tps))
             } else {
                 Ok((
-                    get_type_name_for_schema(&property.schema.common)?.to_token_stream(false, false)?,
+                    type_name_gen(&get_type_name_for_schema(&property.schema.common)?, false, false)?,
                     Vec::new(),
                 ))
             }