flecs_ecs/addons/doc/
doc.rs

1//! The doc module allows for documenting entities (and thus components, systems)
2//! by adding brief and/or detailed descriptions as components. Documentation
3//! added with the doc module can be retrieved at runtime, and can be used by
4//! tooling such as UIs or documentation frameworks.
5
6use crate::core::*;
7
8#[cfg(feature = "std")]
9extern crate std;
10
11extern crate alloc;
12use alloc::string::String;
13
14//MARK: trait::Doc
15///
16///
17/// ```
18/// use flecs_ecs::{addons::doc::Doc, core::World, macros::Component};
19///
20/// #[derive(Component)]
21/// struct Tag;
22///
23/// let world = World::default();
24/// world.component::<Tag>().set_doc_name("A tag");
25///
26/// world
27///     .entity()
28///     .set_doc_brief("A vast expanse of nothingness.");
29/// ```
30pub trait Doc<'a>: WorldProvider<'a> + Into<Entity> + Clone {
31    //MARK: _getters
32
33    /// Get human readable name for an entity.
34    ///
35    /// # Returns
36    ///
37    /// The human readable name of the entity.
38    ///
39    /// # See also
40    ///
41    /// * [`World::doc_name()`]
42    fn doc_name(&self) -> Option<String> {
43        self.world().doc_name(self.clone())
44    }
45
46    /// Get brief description for an entity.
47    ///
48    /// # Returns
49    ///
50    /// The brief description of the entity.
51    ///
52    /// # See also
53    ///
54    /// * [`World::doc_brief()`]
55    fn doc_brief(&self) -> Option<String> {
56        self.world().doc_brief(self.clone())
57    }
58
59    /// Get detailed description for an entity.
60    ///
61    /// # Returns
62    ///
63    /// The detailed description of the entity.
64    ///
65    /// # See also
66    ///
67    /// * [`World::doc_detail()`]
68    fn doc_detail(&self) -> Option<String> {
69        self.world().doc_detail(self.clone())
70    }
71
72    /// Get link to external documentation for an entity.
73    ///
74    /// # Returns
75    ///
76    /// The link to external documentation of the entity.
77    ///
78    /// # See also
79    ///
80    /// * [`World::doc_link()`]
81    fn doc_link(&self) -> Option<String> {
82        self.world().doc_link(self.clone())
83    }
84
85    /// Get color for an entity.
86    ///
87    /// # Returns
88    ///
89    /// The color of the entity.
90    ///
91    /// # See also
92    ///
93    /// * [`World::doc_color()`]
94    fn doc_color(&self) -> Option<String> {
95        self.world().doc_color(self.clone())
96    }
97
98    /// Get UUID for entity
99    ///
100    /// # Returns
101    ///
102    /// The UUID of the entity.
103    ///
104    /// # See also
105    ///
106    /// * [`World::doc_uuid()`]
107    /// * [`Doc::set_doc_uuid()`]
108    /// * [`World::set_doc_uuid()`]
109    fn doc_uuid(&self) -> Option<String> {
110        self.world().doc_uuid(self.clone())
111    }
112
113    //MARK: _setters
114
115    /// Add human-readable name to entity.
116    ///
117    /// Contrary to entity names, human readable names do not have to be unique and
118    /// can contain special characters used in the query language like '*'.
119    ///
120    /// # Arguments
121    ///
122    /// * `name` - The name to add.
123    ///
124    /// # See also
125    ///
126    /// * [`World::set_doc_name()`]
127    fn set_doc_name(&self, name: &str) -> &Self {
128        self.world().set_doc_name(self.clone(), name);
129        self
130    }
131
132    /// Add brief description to entity.
133    ///
134    /// # Arguments
135    ///
136    /// * `brief` - The brief description to add.
137    ///
138    /// # See also
139    ///
140    /// * [`World::set_doc_brief()`]
141    fn set_doc_brief(&self, brief: &str) -> &Self {
142        self.world().set_doc_brief(self.clone(), brief);
143        self
144    }
145
146    /// Add detailed description to entity.
147    ///
148    /// # Arguments
149    ///
150    /// * `detail` - The detailed description to add.
151    ///
152    /// # See also
153    ///
154    /// * [`World::set_doc_detail()`]
155    fn set_doc_detail(&self, detail: &str) -> &Self {
156        self.world().set_doc_detail(self.clone(), detail);
157        self
158    }
159
160    /// Add link to external documentation to entity.
161    ///
162    /// # Arguments
163    ///
164    /// * `link` - The link to add.
165    ///
166    /// # See also
167    ///
168    /// * [`World::set_doc_link()`]
169    fn set_doc_link(&self, link: &str) -> &Self {
170        self.world().set_doc_link(self.clone(), link);
171        self
172    }
173
174    /// Add color to entity.
175    ///
176    /// UIs can use color as hint to improve visualizing entities.
177    ///
178    /// # Arguments
179    ///
180    /// * `world` - The world.
181    /// * `color` - The color to add.
182    ///
183    /// # See also
184    ///
185    /// * [`World::set_doc_color()`]
186    fn set_doc_color(&self, color: &str) -> &Self {
187        self.world().set_doc_color(self.clone(), color);
188        self
189    }
190
191    /// Set doc UUID.
192    /// This adds `(flecs.doc.Description, flecs.doc.Uuid)` to the entity.
193    ///
194    /// # Arguments
195    ///
196    /// * `uuid` - The UUID to add.
197    ///
198    /// # See also
199    /// * [`World::set_doc_uuid()`]
200    /// * [`World::doc_uuid()`]
201    /// * [`Doc::doc_uuid()`]
202    fn set_doc_uuid(&self, uuid: &str) -> &Self {
203        self.world().set_doc_uuid(self.clone(), uuid);
204        self
205    }
206}
207
208impl<'a, T> Doc<'a> for T where T: Into<Entity> + WorldProvider<'a> + Clone {}
flecs_ecs/addons/doc/doc.rs

flecs_ecs/addons/doc/
doc.rs
