gm_docs_parser/
lib.rs

1#![warn(missing_docs)]
2
3//! These are typings for the Gms2 Manual Documentation, which is
4//! provided by the executable made by this crate. That executable is not
5//! published on crates.io, but is at the projects Github page, where users can
6//! get the exe in the releases page.
7//!
8//! The purpose of these typings are for downstream consumers of the Manual,
9//! who will create their database offline and load those typings using Serde.
10//! These typings do not assume that users will create them at all, but they are
11//! made entirely public for simplicity. Therefore, **this library makes guarentees
12//! which the type system does not and could not support**, as the guarentees this
13//! documentation makes are held up by invariants in the `exe` which creates the Json,
14//! rather than the type system itself.
15
16use serde::{Deserialize, Serialize};
17use std::collections::BTreeMap;
18use url::Url;
19
20/// The typings for the Entire Manual. This can be read as one massive Json.
21#[derive(Debug, Clone, PartialEq, Eq, Ord, PartialOrd, Serialize, Deserialize)]
22pub struct GmManual {
23    /// The built in functions within the manual created by Yyg.
24    pub functions: BTreeMap<String, GmManualFunction>,
25    /// The built in variables within the manual created by Yyg.
26    pub variables: BTreeMap<String, GmManualVariable>,
27    /// Many of the built in constants within the manual created by Yyg. Constants are
28    /// difficult to accurately scrape from the documentation, so there will be missing
29    /// constants as the scrapper gets better and better at finding them.
30    pub constants: BTreeMap<String, GmManualConstant>,
31}
32
33/// A function scraped from the Gm Manual.
34#[derive(Debug, Clone, PartialEq, Eq, Ord, PartialOrd, Serialize, Deserialize)]
35#[serde(rename_all = "camelCase")]
36pub struct GmManualFunction {
37    /// The name of the function
38    pub name: String,
39
40    /// The parameters of the function.
41    pub parameters: Vec<GmManualFunctionParameter>,
42
43    /// The count of the number of required parameters.
44    pub required_parameters: usize,
45
46    /// By `variadic`, we mean if the final parameter can take "infinite" arguments. Examples
47    /// are `ds_list_add`, where users can invoke it as `ds_list_add(list, index, 1, 2, 3, 4 /* etc */);`
48    pub is_variadic: bool,
49
50    /// The example given in the Manual.
51    pub example: String,
52
53    /// The description of what the function does.
54    pub description: String,
55
56    /// What the function returns.
57    pub returns: String,
58
59    /// The link to the webpage.
60    pub link: Url,
61}
62
63/// A variable scraped from the GmManual.
64#[derive(Debug, Clone, PartialEq, Eq, Ord, PartialOrd, Serialize, Deserialize)]
65#[serde(rename_all = "camelCase")]
66pub struct GmManualVariable {
67    /// The name of the variable
68    pub name: String,
69
70    /// The example given in the Manual.
71    pub example: String,
72
73    /// The description of what the variable does.
74    pub description: String,
75
76    /// The type of the variable.
77    pub returns: String,
78
79    /// The link to the webpage.
80    pub link: Url,
81}
82
83/// A parameter and description from the manual. Parameters do not directly indicate if they are optional
84/// or variadic -- instead, look at [`GmManualFunction`].
85///
86/// [`GmManualFunction`]: struct.GmManualFunction.html
87#[derive(Debug, Clone, PartialEq, Eq, Ord, PartialOrd, Default, Serialize, Deserialize)]
88#[serde(rename_all = "camelCase")]
89pub struct GmManualFunctionParameter {
90    /// The name of the parameter.
91    pub parameter: String,
92
93    /// A description given of the parameter.
94    pub description: String,
95}
96
97/// A constant parsed from the GmManual.
98///
99/// Because parsing constants is difficult, none of these fields are guarenteed to be non-empty except
100/// for [`name`]. Additionally, a constant might have more data than just a description -- if that is the case,
101/// additional data will be noted in [`secondary_descriptors`]. As a consequence of this, if the `description`
102/// is empty, then `secondary_descriptors` will also always be empty.
103#[derive(Debug, Clone, PartialEq, Eq, Ord, PartialOrd, Serialize, Deserialize)]
104#[serde(rename_all = "camelCase")]
105pub struct GmManualConstant {
106    /// The name of the constant
107    pub name: String,
108
109    /// A description of the constant
110    pub description: String,
111
112    /// The link to the webpage.
113    pub link: Url,
114
115    /// Additional descriptors present. Most of the time, this will be None, but can
116    /// have some Descriptors and Values present.
117    pub secondary_descriptors: Option<BTreeMap<String, String>>,
118}
gm_docs_parser/lib.rs

gm_docs_parser/
lib.rs
