[DOCS] Document client functions and user {major}.{minor} version in links (#53)

* Document all associated functions
* Use major.minor version in doc attribute links

This commit updates the api_generator to change references to master or current in documentation
links to the major.minor version of the api_generator package version. With this change, documentation
links to the correct version for the client version.

* Update doc links with /master and /current

Author: russcam

api_generator/Cargo.toml

@@ -18,9 +18,11 @@ reduce = "0.1.2"
 regex = "1.3.1"
 reqwest = "~0.9"
 rustfmt-nightly="1.4.8"
+semver = "0.9.0"
 serde = "~1"
 serde_json = "~1"
 serde_derive = "~1"
 syn = { version = "~0.11", features = ["full"] }
 rayon = "1.2.0"
+url = "2.1.1"
 void = "1.0.2"

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

@@ -483,12 +483,12 @@ impl<'a> RequestBuilder<'a> {
             endpoint.documentation.url.as_ref(),
         ) {
             (Some(d), Some(u)) if Url::parse(u).is_ok() => lit(format!(
-                "Builder for the [{} API]({}). {}",
+                "Builder for the [{} API]({})\n\n{}",
                 api_name_for_docs, u, d
             )),
-            (Some(d), None) => lit(format!("Builder for the {} API. {}", api_name_for_docs, d)),
+            (Some(d), None) => lit(format!("Builder for the {} API\n\n{}", api_name_for_docs, d)),
             (None, Some(u)) if Url::parse(u).is_ok() => lit(format!(
-                "Builder for the [{} API]({}).",
+                "Builder for the [{} API]({})",
                 api_name_for_docs, u
             )),
             _ => lit(format!("Builder for the {} API", api_name_for_docs)),
@@ -553,17 +553,27 @@ impl<'a> RequestBuilder<'a> {
             }
         };
 
-        let method_doc = match &endpoint.documentation.description {
-            Some(description) => Some(doc(description)),
-            _ => None,
+        let api_name_for_docs = split_on_pascal_case(builder_name);
+        let method_doc = match (
+            endpoint.documentation.description.as_ref(),
+            endpoint.documentation.url.as_ref(),
+        ) {
+            (Some(d), Some(u)) if Url::parse(u).is_ok() => doc(format!(
+                "[{} API]({})\n\n{}",
+                api_name_for_docs, u, d)
+            ),
+            (Some(d), None) => doc(format!("{} API\n\n{}", api_name_for_docs, d)),
+            (None, Some(u)) if Url::parse(u).is_ok() => doc(format!(
+                "[{} API]({})",
+                api_name_for_docs, u
+            )),
+            _ => doc(format!("{} API", api_name_for_docs)),
         };
 
-        let clone_expr = {
-            if is_root_method {
-                quote!(&self)
-            } else {
-                quote!(&self.client)
-            }
+        let clone_expr = if is_root_method {
+            quote!(&self)
+        } else {
+            quote!(&self.client)
         };
 
         if enum_builder.contains_single_parameterless_part() {
@@ -610,7 +620,7 @@ impl<'a> RequestBuilder<'a> {
     }
 
     /// builds the AST that represent the builder structs
-    /// and the ctor function for the builder struct on the namespace client
+    /// and the ctor function for the builder struct on the root/namespace client
     pub fn build(self) -> (Tokens, Tokens) {
         let builder_struct = Self::create_builder_struct(
             self.builder_name,

api_generator/src/api_generator/mod.rs

@@ -17,6 +17,8 @@ use serde::de::{MapAccess, Visitor};
 use std::marker::PhantomData;
 use std::str::FromStr;
 use void::Void;
+use url;
+use semver::Version;
 
 mod code_gen;
 
@@ -146,10 +148,64 @@ pub struct Body {
     pub serialize: Option<String>,
 }
 
+lazy_static! {
+    static ref MAJOR_MINOR_VERSION: Version = semver::Version::parse(env!("CARGO_PKG_VERSION")).unwrap();
+}
+
+/// Wraps the URL string to replace master or current in URL path with the
+/// major.minor version of the api_generator.
+fn documentation_url_string<'de, D>(deserializer: D) -> Result<String, D::Error>
+    where
+        D: Deserializer<'de>,
+{
+    let s = String::deserialize(deserializer)?;
+    Ok(DocumentationUrlString::replace_version_in_url(s))
+}
+
+/// A Documentation URL string
+#[derive(Debug, Deserialize, PartialEq, Clone)]
+pub struct DocumentationUrlString(#[serde(deserialize_with = "documentation_url_string")] pub String);
+
+impl DocumentationUrlString {
+    fn from_url(s: String) -> Self {
+        let s = Self::replace_version_in_url(s);
+        Self(s)
+    }
+
+    fn replace_version_in_url(s: String) -> String {
+        match url::Url::parse(&s) {
+            Ok(u) => {
+                let mut u = u;
+                if u.path().contains("/master") {
+                    u.set_path(u.path().replace("/master", format!("/{}.{}", MAJOR_MINOR_VERSION.major, MAJOR_MINOR_VERSION.minor).as_str()).as_str());
+                } else if u.path().contains("/current") {
+                    u.set_path(u.path().replace("/current", format!("/{}.{}", MAJOR_MINOR_VERSION.major, MAJOR_MINOR_VERSION.minor).as_str()).as_str());
+                }
+                u.into_string()
+            },
+            Err(_) => s
+        }
+    }
+}
+
+impl core::ops::Deref for DocumentationUrlString {
+    type Target = String;
+
+    fn deref(self: &'_ Self) -> &'_ Self::Target {
+        &self.0
+    }
+}
+
+impl fmt::Display for DocumentationUrlString {
+    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+        write!(f, "{}", self.0)
+    }
+}
+
 /// Documentation for an API endpoint
 #[derive(Debug, PartialEq, Deserialize, Clone)]
 pub struct Documentation {
-    pub url: Option<String>,
+    pub url: Option<DocumentationUrlString>,
     pub description: Option<String>,
 }
 
@@ -158,7 +214,7 @@ impl FromStr for Documentation {
 
     fn from_str(s: &str) -> Result<Self, Self::Err> {
         Ok(Documentation {
-            url: Some(s.to_string()),
+            url: Some(DocumentationUrlString::from_url(s.to_owned())),
             description: None,
         })
     }