Add documentation for generated enums

This commit adds documentation for generated enums. The documentation is sourced
from the rest API specs.

Author: russcam

api_generator/src/api_generator/code_gen/mod.rs

@@ -41,7 +41,7 @@ fn ident<I: AsRef<str>>(name: I) -> syn::Ident {
 }
 
 /// AST for document attribute
-fn doc(comment: String) -> syn::Attribute {
+fn doc<I: Into<String>>(comment: I) -> syn::Attribute {
     syn::Attribute {
         style: syn::AttrStyle::Outer,
         value: syn::MetaItem::NameValue(ident("doc".to_string()), lit(comment)),

api_generator/src/api_generator/code_gen/params.rs

@@ -42,8 +42,14 @@ fn generate_param(tokens: &mut Tokens, e: &ApiEnum) {
         })
         .unzip();
 
+    let doc = match &e.description {
+        Some(description) => Some(code_gen::doc(description)),
+        None => None,
+    };
+
     let generated_enum_tokens = quote!(
         #[derive(Debug, PartialEq, Deserialize, Serialize, Clone, Copy)]
+        #doc
         pub enum #name {
             #(#[serde(rename = #renames)] #variants),*
         }

api_generator/src/api_generator/code_gen/request/request_builder.rs

@@ -227,7 +227,7 @@ impl<'a> RequestBuilder<'a> {
             ident: ident("body<T>"),
             vis: syn::Visibility::Public,
             defaultness: syn::Defaultness::Final,
-            attrs: vec![doc("The body for the API call".into())],
+            attrs: vec![doc("The body for the API call")],
             node: syn::ImplItemKind::Method(
                 syn::MethodSig {
                     unsafety: syn::Unsafety::Normal,
@@ -266,7 +266,7 @@ impl<'a> RequestBuilder<'a> {
 
     /// Creates the AST for a builder fn to add a HTTP header
     fn create_header_fn(field: &syn::Ident) -> syn::ImplItem {
-        let doc_attr = doc("Adds a HTTP header".into());
+        let doc_attr = doc("Adds a HTTP header");
 
         syn::ImplItem {
             ident: ident("header"),
@@ -315,7 +315,7 @@ impl<'a> RequestBuilder<'a> {
         let value_ident = ident(&name);
         let ty = typekind_to_ty(&f.0, f.1.ty, true);
         let doc_attr = match &f.1.description {
-            Some(docs) => vec![doc(docs.into())],
+            Some(docs) => vec![doc(docs)],
             _ => vec![],
         };
 
@@ -554,7 +554,7 @@ impl<'a> RequestBuilder<'a> {
         };
 
         let method_doc = match &endpoint.documentation.description {
-            Some(description) => Some(doc(description.into())),
+            Some(description) => Some(doc(description)),
             _ => None,
         };
 

api_generator/src/api_generator/code_gen/url/enum_builder.rs

@@ -135,7 +135,7 @@ impl<'a> EnumBuilder<'a> {
     fn parts_none() -> syn::Variant {
         syn::Variant {
             ident: ident("None"),
-            attrs: vec![doc("No parts".into())],
+            attrs: vec![doc("No parts")],
             data: syn::VariantData::Unit,
             discriminant: None,
         }

api_generator/src/api_generator/mod.rs

@@ -233,6 +233,7 @@ pub struct Common {
 /// An enum defined in the REST API specs
 pub struct ApiEnum {
     pub name: String,
+    pub description: Option<String>,
     pub values: Vec<String>,
 }
 
@@ -385,6 +386,7 @@ fn read_api(branch: &str, download_dir: &PathBuf) -> Result<Api, failure::Error>
 
                 enums.insert(ApiEnum {
                     name: param.0.to_string(),
+                    description: param.1.description.clone(),
                     values: options,
                 });
             }

elasticsearch/src/generated/params.rs

@@ -16,6 +16,7 @@
 // -----------------------------------------------
 use serde::{Deserialize, Serialize};
 #[derive(Debug, PartialEq, Deserialize, Serialize, Clone, Copy)]
+#[doc = "The unit in which to display byte values"]
 pub enum Bytes {
     #[serde(rename = "b")]
     B,
@@ -41,20 +42,23 @@ pub enum Bytes {
     Pb,
 }
 #[derive(Debug, PartialEq, Deserialize, Serialize, Clone, Copy)]
+#[doc = "What to do when the delete by query hits version conflicts?"]
 pub enum Conflicts {
     #[serde(rename = "abort")]
     Abort,
     #[serde(rename = "proceed")]
     Proceed,
 }
 #[derive(Debug, PartialEq, Deserialize, Serialize, Clone, Copy)]
+#[doc = "The default operator for query string query (AND or OR)"]
 pub enum DefaultOperator {
     #[serde(rename = "AND")]
     And,
     #[serde(rename = "OR")]
     Or,
 }
 #[derive(Debug, PartialEq, Deserialize, Serialize, Clone, Copy)]
+#[doc = "Whether to expand wildcard expression to concrete indices that are open, closed or both."]
 pub enum ExpandWildcards {
     #[serde(rename = "open")]
     Open,
@@ -66,6 +70,7 @@ pub enum ExpandWildcards {
     All,
 }
 #[derive(Debug, PartialEq, Deserialize, Serialize, Clone, Copy)]
+#[doc = "Group tasks by nodes or parent/child relationships"]
 pub enum GroupBy {
     #[serde(rename = "nodes")]
     Nodes,
@@ -75,6 +80,7 @@ pub enum GroupBy {
     None,
 }
 #[derive(Debug, PartialEq, Deserialize, Serialize, Clone, Copy)]
+#[doc = "A health status (\"green\", \"yellow\", or \"red\" to filter only indices matching the specified health status"]
 pub enum Health {
     #[serde(rename = "green")]
     Green,
@@ -84,6 +90,7 @@ pub enum Health {
     Red,
 }
 #[derive(Debug, PartialEq, Deserialize, Serialize, Clone, Copy)]
+#[doc = "Specify the level of detail for returned information"]
 pub enum Level {
     #[serde(rename = "cluster")]
     Cluster,
@@ -93,13 +100,15 @@ pub enum Level {
     Shards,
 }
 #[derive(Debug, PartialEq, Deserialize, Serialize, Clone, Copy)]
+#[doc = "Explicit operation type. Defaults to `index` for requests with an explicit document ID, and to `create`for requests without an explicit document ID"]
 pub enum OpType {
     #[serde(rename = "index")]
     Index,
     #[serde(rename = "create")]
     Create,
 }
 #[derive(Debug, PartialEq, Deserialize, Serialize, Clone, Copy)]
+#[doc = "If `true` then refresh the effected shards to make this operation visible to search, if `wait_for` then wait for a refresh to make this operation visible to search, if `false` (the default) then do nothing with refreshes."]
 pub enum Refresh {
     #[serde(rename = "true")]
     True,
@@ -109,13 +118,15 @@ pub enum Refresh {
     WaitFor,
 }
 #[derive(Debug, PartialEq, Deserialize, Serialize, Clone, Copy)]
+#[doc = "Search operation type"]
 pub enum SearchType {
     #[serde(rename = "query_then_fetch")]
     QueryThenFetch,
     #[serde(rename = "dfs_query_then_fetch")]
     DfsQueryThenFetch,
 }
 #[derive(Debug, PartialEq, Deserialize, Serialize, Clone, Copy)]
+#[doc = "The multiplier in which to display values"]
 pub enum Size {
     #[serde(rename = "k")]
     K,
@@ -129,6 +140,7 @@ pub enum Size {
     P,
 }
 #[derive(Debug, PartialEq, Deserialize, Serialize, Clone, Copy)]
+#[doc = "Specify suggest mode"]
 pub enum SuggestMode {
     #[serde(rename = "missing")]
     Missing,
@@ -138,6 +150,7 @@ pub enum SuggestMode {
     Always,
 }
 #[derive(Debug, PartialEq, Deserialize, Serialize, Clone, Copy)]
+#[doc = "The unit in which to display time values"]
 pub enum Time {
     #[serde(rename = "d")]
     D,
@@ -155,6 +168,7 @@ pub enum Time {
     Nanos,
 }
 #[derive(Debug, PartialEq, Deserialize, Serialize, Clone, Copy)]
+#[doc = "The type to sample (default: cpu)"]
 pub enum Type {
     #[serde(rename = "cpu")]
     Cpu,
@@ -164,6 +178,7 @@ pub enum Type {
     Block,
 }
 #[derive(Debug, PartialEq, Deserialize, Serialize, Clone, Copy)]
+#[doc = "Specific version type"]
 pub enum VersionType {
     #[serde(rename = "internal")]
     Internal,
@@ -173,6 +188,7 @@ pub enum VersionType {
     ExternalGte,
 }
 #[derive(Debug, PartialEq, Deserialize, Serialize, Clone, Copy)]
+#[doc = "Wait until all currently queued events with the given priority are processed"]
 pub enum WaitForEvents {
     #[serde(rename = "immediate")]
     Immediate,
@@ -188,6 +204,7 @@ pub enum WaitForEvents {
     Languid,
 }
 #[derive(Debug, PartialEq, Deserialize, Serialize, Clone, Copy)]
+#[doc = "Wait until cluster is in a specific state"]
 pub enum WaitForStatus {
     #[serde(rename = "green")]
     Green,

elasticsearch/src/http/request.rs

@@ -9,10 +9,11 @@ use serde::Serialize;
 /// expect JSON, however, there are some APIs that expect newline-delimited JSON (NDJSON).
 /// The [Body] trait allows modelling different API body implementations.
 pub trait Body {
-    /// A ready-made immutable buffer that can be used to avoid writing
+    /// An existing immutable buffer that can be used to avoid writing
+    /// having to write to another buffer that will then be written to the request stream.
     ///
     /// If this method returns `Some`, the bytes must be the same as
-    /// what would be written by `write`.
+    /// those that would be written by `write`.
     fn bytes(&self) -> Option<Bytes> {
         None
     }

elasticsearch/src/params/mod.rs

@@ -3,7 +3,7 @@
 pub use super::generated::params::*;
 use serde::{Deserialize, Serialize};
 
-/// Allows you to control how the total number of hits should be tracked.
+/// Control how the total number of hits should be tracked.
 ///
 /// When set to `Track` with a value `true`, the response will always track the number of hits that
 /// match the query accurately.