rl_lang/docs/
entry.rs

1//! Static data types used to represent all documentation entries.
2//!
3//! Every entry is a `'static` struct so the entire doc system lives in the
4//! binary with zero heap allocation at startup.
5
6use serde::Serialize;
7
8/// A single stdlib function's documentation.
9#[derive(Serialize)]
10pub struct FnEntry {
11    /// The function signature as it appears in rl (e.g. `"arr_push(arr, value)"`).
12    pub signature: &'static str,
13    /// What the function does, including edge cases and constraints.
14    pub description: &'static str,
15    /// A runnable rl example showing typical usage.
16    pub example: &'static str,
17    /// The expected stdout of `example`, for doctest-style checking.
18    /// `None` when the example's result is shown inline (e.g. as a trailing
19    /// comment) rather than printed.
20    pub expected_output: Option<&'static str>,
21    /// The return type/value description (e.g. `"float"`, `"Result[int]"`).
22    pub returns: &'static str,
23    /// When and why this function raises a runtime error. `None` if the
24    /// function is infallible.
25    pub errors: Option<&'static str>,
26    /// Related function names to cross-link (e.g. `["to_hex", "to_oct"]`).
27    /// Empty if there's nothing closely related.
28    pub see_also: &'static [&'static str],
29    /// The version this function was introduced in (e.g. `"v0.1.4"`).
30    /// `None` for functions that predate version tracking.
31    pub since: Option<&'static str>,
32}
33
34/// A stdlib module's documentation, grouping related [`FnEntry`]s together.
35#[derive(Serialize)]
36pub struct StdEntry {
37    /// The module name as used in imports (e.g. `"io"`, `"math::consts"`).
38    pub name: &'static str,
39    /// A short description of the module's purpose.
40    pub description: &'static str,
41    /// All documented functions in this module.
42    pub functions: &'static [&'static FnEntry],
43    /// The version this module was introduced in (e.g. `"v0.1.4"`).
44    /// `None` for modules that predate version tracking.
45    pub since: Option<&'static str>,
46    /// Whether this module's API is still subject to change and shouldn't
47    /// be relied on for backward compatibility yet.
48    pub unstable: bool,
49}
50
51/// Coarse grouping used to organize the concept index / nav.
52#[derive(Serialize)]
53pub enum ConceptCategory {
54    /// Basic language syntax (comments, literals, general structure).
55    Syntax,
56    /// Type system concepts (casting, type annotations, `Result[T]`, etc.).
57    Types,
58    /// Branching and looping constructs (`if`/`elif`/`else`, `for`, `while`).
59    ControlFlow,
60    /// Function definitions, lambdas, and closures.
61    Functions,
62    /// Imports and the module system.
63    Modules,
64    /// CLI, LSP, REPL, and other developer-tooling concepts.
65    Tooling,
66    /// Errors, `Result[T]`, and failure handling.
67    ErrorHandling,
68}
69
70/// What role a [`DescriptionEntry`] plays, so the renderer can style it
71/// differently (e.g. a pitfall as a warning callout).
72#[derive(Serialize)]
73pub enum DescriptionKind {
74    /// Ordinary prose explaining how or why something works.
75    Explanation,
76    /// A syntax reference block, usually paired with a minimal example.
77    Syntax,
78    /// A common mistake or gotcha readers should watch out for.
79    Pitfall,
80    /// A supplementary aside that isn't essential to the main explanation.
81    Note,
82}
83
84/// Documentation for a language concept (variables, loops, types, etc.).
85#[derive(Serialize)]
86pub struct ConceptEntry {
87    /// The concept name shown as a section header (e.g. `"arrays"`, `"for loops"`).
88    pub name: &'static str,
89    /// One-line blurb for index/nav pages, distinct from the full descriptions.
90    pub summary: &'static str,
91    /// Coarse category for grouping in the concept index.
92    pub category: ConceptCategory,
93    /// Concept names a reader should understand first. Empty if this is a
94    /// foundational concept with no prerequisites.
95    pub prerequisites: &'static [&'static str],
96    /// One or more description+example pairs explaining this concept.
97    pub descriptions: &'static [DescriptionEntry],
98    /// Common mistakes specific to this concept. Empty if there are none
99    /// worth calling out.
100    pub pitfalls: &'static [&'static str],
101    /// Related concept names to cross-link (e.g. `["arrays", "for loops"]`).
102    pub related: &'static [&'static str],
103    /// stdlib module names that implement or relate to this concept
104    /// (e.g. `"arrays"` concept relates to the `"array"` module).
105    pub related_stdlib: &'static [&'static str],
106    /// The version this concept/syntax was introduced or last changed in.
107    /// `None` for concepts that predate version tracking.
108    pub since: Option<&'static str>,
109}
110
111/// A single description with one or more accompanying rl code examples.
112#[derive(Serialize)]
113pub struct DescriptionEntry {
114    /// What role this block plays (explanation, syntax, pitfall, note).
115    pub kind: DescriptionKind,
116    /// Optional subsection heading, for concepts with multiple distinct parts.
117    pub title: Option<&'static str>,
118    /// Prose explanation of this aspect of the concept.
119    pub description: &'static str,
120    /// One or more rl snippets illustrating the description.
121    pub examples: &'static [&'static str],
122    /// Expected stdout for each entry in `examples`, same length as
123    /// `examples` if present, empty if outputs aren't checked.
124    pub expected_output: &'static [&'static str],
125}
rl_lang/docs/entry.rs

rl_lang/docs/
entry.rs
