doku/printers/json/formatting/
auto_comments.rs

1use crate::*;
2
3/// Determines which auto-comments - _hints_, so to say - should get displayed.
4///
5/// Sometimes Doku is able to automatically infer certain properties about a
6/// type and provide a dedicated hint such as "this field is optional". This
7/// struct allows to configure whether you'd like for such comments to be
8/// printed or not.
9#[derive(Clone, Debug, Serialize, Deserialize)]
10#[serde(deny_unknown_fields)]
11pub struct AutoComments {
12    /// When set, displays hints for arrays of known sizes:
13    ///
14    /// ```
15    /// use doku::Document;
16    ///
17    /// #[derive(Document)]
18    /// struct Person {
19    ///     friends: [String; 3],
20    /// }
21    ///
22    /// let fmt = doku::json::Formatting {
23    ///     auto_comments: doku::json::AutoComments {
24    ///         array_size: true,
25    ///         ..Default::default()
26    ///     },
27    ///     ..Default::default()
28    /// };
29    ///
30    /// let doc = doku::to_json_fmt::<Person>(&fmt);
31    ///
32    /// doku::assert_doc!(r#"
33    ///   {
34    ///     // Must contain exactly 3 elements
35    ///     "friends": [
36    ///       "string",
37    ///       /* ... */
38    ///     ]
39    ///   }
40    /// "#, doc);
41    /// ```
42    pub array_size: bool,
43
44    /// When set, displays hints for optional values:
45    ///
46    /// ```
47    /// use doku::Document;
48    ///
49    /// #[derive(Document)]
50    /// struct Person {
51    ///     friend: Option<String>,
52    /// }
53    ///
54    /// let fmt = doku::json::Formatting {
55    ///     auto_comments: doku::json::AutoComments {
56    ///         optional: true,
57    ///         ..Default::default()
58    ///     },
59    ///     ..Default::default()
60    /// };
61    ///
62    /// let doc = doku::to_json_fmt::<Person>(&fmt);
63    ///
64    /// doku::assert_doc!(r#"
65    ///   {
66    ///     // Optional
67    ///     "friend": "string"
68    ///   }
69    /// "#, doc);
70    /// ```
71    pub optional: bool,
72}
73
74impl AutoComments {
75    pub fn all() -> Self {
76        Self {
77            array_size: true,
78            optional: true,
79        }
80    }
81
82    pub fn none() -> Self {
83        Self {
84            array_size: false,
85            optional: false,
86        }
87    }
88}
89
90impl Default for AutoComments {
91    fn default() -> Self {
92        Self::all()
93    }
94}
doku/printers/json/formatting/auto_comments.rs

doku/printers/json/formatting/
auto_comments.rs
