From 9a85e0b2a1888972fd8c436a405ceda5e4941a69 Mon Sep 17 00:00:00 2001
From: Graham Esau <gesau@hotmail.co.uk>
Date: Sun, 20 Oct 2019 15:46:09 +0100
Subject: [PATCH] Start adding doc comments

---
 schemars/src/lib.rs       | 35 +++++++++++++++++++++++++++++++++--
 schemars/src/macros.rs    | 14 ++++++++++++++
 schemars/src/schema.rs    |  1 +
 schemars/tests/flatten.rs |  1 +
 4 files changed, 49 insertions(+), 2 deletions(-)

diff --git a/schemars/src/lib.rs b/schemars/src/lib.rs
index 7b6d644..d9ca37d 100644
--- a/schemars/src/lib.rs
+++ b/schemars/src/lib.rs
@@ -1,5 +1,3 @@
-#![allow(clippy::large_enum_variant)]
-
 pub type Map<K, V> = std::collections::BTreeMap<K, V>;
 pub type Set<T> = std::collections::BTreeSet<T>;
 
@@ -8,22 +6,55 @@ mod json_schema_impls;
 #[macro_use]
 mod macros;
 
+/// JSON Schema generator and settings.
 pub mod gen;
+/// JSON Schema types.
 pub mod schema;
 
 pub use schemars_derive::*;
 
 use schema::Schema;
 
+/// A type which can be described as a JSON Schema document.
+///
+/// This is implemented for many Rust primitive and standard library types.
+///
+/// This can also be automatically derived on most custom types with `#[derive(JsonSchema)]`.
+///
+/// ```
+/// use schemars::{schema_for, JsonSchema};
+///
+/// #[derive(JsonSchema)]
+/// struct MyStruct {
+///     foo: i32,
+/// }
+///
+/// let my_schema = schema_for!(MyStruct);
+/// ```
 pub trait JsonSchema {
+    /// Whether JSON Schemas generated for this type should be re-used where possible using the `$ref` keyword.
+    ///
+    /// For trivial types (such as primitives), this should return `false`. For more complex types, it should return `true`.
+    /// For recursive types, this *must* return `true` to prevent infinite cycles when generating schemas.
+    ///
+    /// By default, this returns `true`.
     fn is_referenceable() -> bool {
         true
     }
 
+    /// The name of the generated JSON Schema.
+    ///
+    /// This is used as the title for root schemas, and the key within the `definitions` property for subschemas.
     fn schema_name() -> String;
 
+    /// Generates a JSON Schema for this type.
+    ///
+    /// This should not return a `$ref` schema.
     fn json_schema(gen: &mut gen::SchemaGenerator) -> Schema;
 
+    /// Helper for generating schemas for flattened `Option` fields.
+    ///
+    /// This should not need to be called or implemented by code outside of `schemars`.
     #[doc(hidden)]
     fn json_schema_optional(gen: &mut gen::SchemaGenerator) -> Schema {
         Self::json_schema(gen)
diff --git a/schemars/src/macros.rs b/schemars/src/macros.rs
index e2b611d..23f141f 100644
--- a/schemars/src/macros.rs
+++ b/schemars/src/macros.rs
@@ -1,3 +1,17 @@
+/// Generates a [`Schema`](schema::Schema) for the given type using default settings.
+///
+/// The type must implement [`JsonSchema`].
+///
+/// ```
+/// use schemars::{schema_for, JsonSchema};
+///
+/// #[derive(JsonSchema)]
+/// struct MyStruct {
+///     foo: i32,
+/// }
+///
+/// let my_schema = schema_for!(MyStruct);
+/// ```
 #[macro_export]
 macro_rules! schema_for {
     ($type:path) => {
diff --git a/schemars/src/schema.rs b/schemars/src/schema.rs
index 6299338..1b3837f 100644
--- a/schemars/src/schema.rs
+++ b/schemars/src/schema.rs
@@ -3,6 +3,7 @@ use crate::{JsonSchema, Map, Set};
 use serde::{Deserialize, Serialize};
 use serde_json::Value;
 
+#[allow(clippy::large_enum_variant)]
 #[derive(Serialize, Deserialize, Debug, Clone, PartialEq, JsonSchema)]
 #[serde(untagged)]
 pub enum Schema {
diff --git a/schemars/tests/flatten.rs b/schemars/tests/flatten.rs
index a191666..304f70c 100644
--- a/schemars/tests/flatten.rs
+++ b/schemars/tests/flatten.rs
@@ -21,6 +21,7 @@ struct Deep1 {
     v: Vec<i32>,
 }
 
+#[allow(clippy::option_option)]
 #[derive(Debug, JsonSchema)]
 struct Deep2 {
     b: bool,