fixup docs

Author: Nertsal

crates/stecs-derive/src/split.rs

@@ -213,7 +213,7 @@ impl Struct {
 
             let struct_ref_doc = format!(
                 r#"Generated by `#[derive(SplitFields)]`.
-This struct is a version of `{struct_name}` that holds references to its fields."#
+This struct is a version of [`{struct_name}`] that holds references to its fields."#
             );
 
             let struct_ref = quote! {
@@ -267,7 +267,7 @@ This struct is a version of `{struct_name}` that holds references to its fields.
 
             let struct_ref_mut_doc = format!(
                 r#"Generated by `#[derive(SplitFields)]`.
-This struct is a version of `{struct_name}` that holds mutable references to its fields."#
+This struct is a version of [`{struct_name}`] that holds mutable references to its fields."#
             );
 
             let struct_ref = quote! {
@@ -349,9 +349,9 @@ This struct is a version of `{struct_name}` that holds mutable references to its
 
             let struct_of_doc = format!(
                 r#"Generated by `#[derive(SplitFields)]`.
-This struct is a version of `{struct_name}` that holds each field in its own [Storage](::stecs::storage::Storage).
+This struct is a version of [`{struct_name}`] that holds each field in its own [Storage](::stecs::storage::Storage).
 
-**Note**: It is used by other generated structures and does not need to be used by user code."#
+**Note**: It is not intended to be used directly, as it is used by other generated structures."#
             );
 
             quote! {
@@ -367,20 +367,36 @@ This struct is a version of `{struct_name}` that holds each field in its own [St
             #[cfg(not(feature = "dynamic"))]
             let dynamic = quote! {};
             #[cfg(feature = "dynamic")]
-            let dynamic =
-                quote! { pub r#dyn: ::stecs::dynamic::DynamicStorage<#generic_family_name>, };
+            let dynamic = quote! {
+                /// Dynamic components attached to the archetype.
+                ///
+                /// **Note**: not intended to be used directly,
+                /// but rather via methods and querying macros.
+                /// *It is only exposed to be accessible in queries*.
+                pub r#dyn: ::stecs::dynamic::DynamicStorage<#generic_family_name>,
+            };
 
             let struct_of_doc = format!(
                 r#"Generated by `#[derive(SplitFields)]`.
-This struct is a version of `{struct_name}` that holds each field in its own [Storage](::stecs::storage::Storage).
+This struct is a version of [`{struct_name}`] that holds each field in its own [Storage](::stecs::storage::Storage).
 
-**Note**: It is not intended to be used directly, but rather as, for example, `StructOf<Vec<{struct_name}>>`."#
+**Note**: It is not intended to be used directly, but rather as, for example, `StructOf<Dense<{struct_name}>>`."#
             );
 
             quote! {
                 #[doc = #struct_of_doc]
                 #vis struct #struct_of_name<#generics_family> {
+                    /// The id's of all existing entities belonging to this archetype.
+                    ///
+                    /// **Note**: not intended to be used directly,
+                    /// but rather via methods and querying macros.
+                    /// *It is only exposed to be accessible in queries*.
                     pub ids: #generic_family_name::Generator,
+                    /// The inner fields of the archetype.
+                    ///
+                    /// **Note**: not intended to be used directly,
+                    /// but rather via methods and querying macros.
+                    /// *It is only exposed to be accessible in queries*.
                     pub inner: #struct_split_name<#generics_family_use>,
                     #dynamic
                 }

examples/blogpost.rs

@@ -5,23 +5,23 @@ use stecs::prelude::*;
 // Define an Archetype
 #[derive(SplitFields)]
 #[split(debug, clone)] // derive Debug and Clone for generated reference types
-struct Monster {
-    position: (f32, f32),
-    health: f32,
-    tick: usize,
-    damage: Option<f32>,
+pub struct Monster {
+    pub position: (f32, f32),
+    pub health: f32,
+    pub tick: usize,
+    pub damage: Option<f32>,
 }
 
 #[derive(SplitFields)]
-struct Corpse {
+pub struct Corpse {
     #[split(nested)]
-    monster: Monster,
-    time: f32,
+    pub monster: Monster,
+    pub time: f32,
 }
 
-struct World {
-    monsters: StructOf<Dense<Monster>>,
-    corpses: StructOf<Dense<Corpse>>,
+pub struct World {
+    pub monsters: StructOf<Dense<Monster>>,
+    pub corpses: StructOf<Dense<Corpse>>,
 }
 
 fn main() {

examples/dynamic.rs

@@ -1,18 +1,18 @@
 use stecs::prelude::*;
 
-struct World {
-    units: StructOf<Dense<Unit>>,
+pub struct World {
+    pub units: StructOf<Dense<Unit>>,
 }
 
 #[derive(Debug, Clone)]
-struct Poisoned {
-    time: f32,
+pub struct Poisoned {
+    pub time: f32,
 }
 
 #[derive(SplitFields)]
 #[split(debug, clone)]
-struct Unit {
-    name: String,
+pub struct Unit {
+    pub name: String,
 }
 
 fn main() {

examples/full.rs

@@ -2,35 +2,35 @@
 use stecs::prelude::*;
 
 #[derive(Clone)] // `StructOf` implements Clone if possible
-struct GameWorld {
-    units: StructOf<Dense<Unit>>,         // UnitStructOf<DenseFamily>,
-    corpses: StructOf<Dense<Corpse>>,     // CorpseStructOf<DenseFamily>,
-    particles: StructOf<Dense<Particle>>, // ParticleStructOf<DenseFamily>,
+pub struct GameWorld {
+    pub units: StructOf<Dense<Unit>>,     // UnitStructOf<DenseFamily>,
+    pub corpses: StructOf<Dense<Corpse>>, // CorpseStructOf<DenseFamily>,
+    pub particles: StructOf<Dense<Particle>>, // ParticleStructOf<DenseFamily>,
 }
 
 #[derive(SplitFields, Debug)]
 #[split(debug)] // derive `Debug` for the `UnitRef` generated struct
-struct Unit {
-    pos: (f32, f32),
-    health: f32,
-    tick: usize,
-    damage: Option<f32>,
+pub struct Unit {
+    pub pos: (f32, f32),
+    pub health: f32,
+    pub tick: usize,
+    pub damage: Option<f32>,
 }
 
 #[derive(SplitFields)]
-struct Corpse {
+pub struct Corpse {
     // Nest `Unit` to efficiently store the fields and to refer to them directly in the queries.
     // But you can still access the whole `Unit` as a single component.
     #[split(nested)]
-    unit: Unit,
-    time: f32,
+    pub unit: Unit,
+    pub time: f32,
 }
 
 #[derive(SplitFields, Debug)]
 #[split(clone)] // implement clone method for the `ParticleRef` generated struct to clone the data into a `Particle`
-struct Particle {
-    pos: (f32, f32),
-    time: f32,
+pub struct Particle {
+    pub pos: (f32, f32),
+    pub time: f32,
 }
 
 fn main() {

examples/generics.rs

@@ -1,22 +1,22 @@
 use stecs::prelude::*;
 
-struct World<'a> {
-    units: StructOf<Dense<Unit<'a>>>,
+pub struct World<'a> {
+    pub units: StructOf<Dense<Unit<'a>>>,
 }
 
 #[derive(SplitFields)]
 #[split(debug, clone)]
-struct Position<F: 'static> {
-    x: F,
-    y: F,
+pub struct Position<F: 'static> {
+    pub x: F,
+    pub y: F,
 }
 
 #[derive(SplitFields)]
 #[split(debug, clone)]
-struct Unit<'a> {
+pub struct Unit<'a> {
     #[split(nested)]
-    position: Position<f32>,
-    name: &'a str,
+    pub position: Position<f32>,
+    pub name: &'a str,
 }
 
 fn main() {

examples/mutations.rs

@@ -1,21 +1,21 @@
 use stecs::prelude::*;
 
-struct World {
-    blocks: StructOf<Dense<Block>>,
+pub struct World {
+    pub blocks: StructOf<Dense<Block>>,
 }
 
 #[derive(SplitFields)]
 #[split(debug)]
-struct Position {
-    x: i64,
+pub struct Position {
+    pub x: i64,
 }
 
 #[derive(SplitFields)]
 #[split(debug)]
-struct Block {
+pub struct Block {
     #[split(nested)]
-    position: Position,
-    height: i64,
+    pub position: Position,
+    pub height: i64,
 }
 
 fn main() {

src/storage/dense.rs

@@ -90,7 +90,7 @@ unsafe impl<K: slotmap::Key> IdGenerator for DenseIdGenerator<K> {
     }
 }
 
-/// Family of [`SlotMap<K, V>`] storages.
+/// Family of [`Dense<K, V>`] storages.
 pub struct DenseFamily<K: slotmap::Key>(std::marker::PhantomData<K>);
 
 impl<K: slotmap::Key> StorageFamily for DenseFamily<K> {

src/storage/sparse.rs

@@ -90,7 +90,7 @@ unsafe impl<K: slotmap::Key> IdGenerator for DenseIdGenerator<K> {
     }
 }
 
-/// Family of [`SlotMap<K, V>`] storages.
+/// Family of [`Sparse<K, V>`] storages.
 pub struct SparseFamily<K: slotmap::Key>(std::marker::PhantomData<K>);
 
 impl<K: slotmap::Key> StorageFamily for SparseFamily<K> {