Add even more docstrings

gen/src/peppi_codegen/common.clj

@@ -327,33 +327,44 @@
           nm
           (str/join ", " (mapv enum-item items))))
 
+(defn emit-docstring
+  [ds]
+  (if ds
+    (some->> ds
+      str/split-lines
+      (mapv #(str "/// " %))
+      (str/join "\n")
+      (format "%s\n"))
+    ""))
+
 (defmethod emit-expr* :struct-field
-  [{:keys [docstring]} nm ty]
-  (cond->> (format "\tpub %s: %s," (emit-ident nm) (emit-type ty))
-    docstring (->> docstring
-                   str/split-lines
-                   (mapv #(str "/// " %))
-                   (str/join "\n"))))
+  [{ds :docstring} nm ty]
+  (format "%spub %s: %s,"
+          (emit-docstring ds)
+          (emit-ident nm)
+          (emit-type ty)))
 
 (defmethod emit-expr* :tuple-struct-field
   [_ ty]
   (format "\tpub %s," (emit-type ty)))
 
 (defmethod emit-expr* :struct
-  [{:keys [attrs]} nm fields]
+  [{:keys [attrs docstring]} nm fields]
   (->> fields
        (mapv emit-expr)
        (str/join "\n")
-       (format "%s\npub struct %s {\n%s\n}"
+       (format "%s%s\npub struct %s {\n%s\n}"
+               (emit-docstring docstring)
                (emit-attrs attrs)
                nm)))
 
 (defmethod emit-expr* :tuple-struct
-  [{:keys [attrs]} nm fields]
+  [{:keys [attrs docstring]} nm fields]
   (->> fields
        (mapv emit-expr)
        (str/join "\n")
-       (format "%s\npub struct %s (\n%s\n);"
+       (format "%s%s\npub struct %s (\n%s\n);"
+               (emit-docstring docstring)
                (emit-attrs attrs)
                nm)))
 

gen/src/peppi_codegen/frame/common.clj

@@ -3,6 +3,11 @@
    [peppi-codegen.common :refer [read-json]]
    [clojure.string :as str]))
 
+(defn field-docstring
+  [desc ver]
+  (some-> desc
+    (cond->> ver (format "*Added: v%s.%s* %s" (ver 0) (ver 1)))))
+
 (defn normalize-field
   [idx field]
   (-> field
@@ -14,6 +19,6 @@
 (defn read-structs
   []
   (-> (read-json "frames.json")
-      (update-vals #(map-indexed normalize-field %))
+      (update-vals (fn [s]
+                     (update s :fields #(map-indexed normalize-field %))))
       (->> (sort-by key))))
-

gen/src/peppi_codegen/frame/immutable/mod.clj

@@ -14,7 +14,7 @@
 (defn struct-field
   [{nm :name, ty :type, ver :version, desc :description}]
   [:struct-field
-   {:docstring desc}
+   {:docstring (field-docstring desc ver)}
    nm
    (cond->> (array-type ty)
      ver (conj ["Option"]))])
@@ -64,13 +64,14 @@
   (list "mutable" ty))
 
 (defmulti struct-decl
-  (fn [[nm fields]]
+  (fn [[nm {:keys [fields]}]]
     (named? fields)))
 
 (defmethod struct-decl true
-  [[nm fields]]
+  [[nm {:keys [description fields]}]]
   [:struct
-   {:attrs {:derive ["Debug"]}}
+   {:attrs {:derive ["Debug"]}
+    :docstring description}
    nm
    (->> (mapv struct-field fields)
         (append [:struct-field
@@ -79,18 +80,19 @@
                  ["Option" "Bitmap"]]))])
 
 (defmethod struct-decl false
-  [[nm fields]]
+  [[nm {:keys [description fields]}]]
   [:tuple-struct
-   {:attrs {:derive ["Debug"]}}
+   {:attrs {:derive ["Debug"]}
+    :docstring description}
    nm
    (mapv tuple-struct-field fields)])
 
 (defn struct-impl
-  [[nm fields]]
+  [[nm {:keys [fields]}]]
   [:impl nm [(transpose-one-fn nm fields)]])
 
 (defn struct-from-impl
-  [[nm fields]]
+  [[nm {:keys [fields]}]]
   [:impl
    {:for nm}
    ["From" (mutable nm)]

gen/src/peppi_codegen/frame/immutable/peppi.clj

@@ -130,7 +130,7 @@
         (named? fields) (append ["validity" "validity"]))]]])
 
 (defn struct-impl
-  [[nm fields]]
+  [[nm {:keys [fields]}]]
   [:impl nm [(data-type-fn fields)
              (into-struct-array-fn fields)
              (from-struct-array-fn fields)]])

gen/src/peppi_codegen/frame/immutable/slippi.clj

@@ -70,7 +70,7 @@
         (append "size"))])
 
 (defn struct-impl
-  [[nm fields]]
+  [[nm {:keys [fields]}]]
   [:impl nm [(write-fn fields)
              (size-fn fields)]])
 

gen/src/peppi_codegen/frame/mutable.clj

@@ -201,7 +201,7 @@
 (defn struct-field
   [{nm :name, ty :type, ver :version, desc :description}]
   [:struct-field
-   {:docstring desc}
+   {:docstring (field-docstring desc ver)}
    nm
    (cond->> (array-type ty)
      ver (conj ["Option"]))])
@@ -213,23 +213,29 @@
      ver (conj ["Option"]))])
 
 (defmulti struct-decl
-  (fn [[nm fields]]
+  (fn [[nm {:keys [fields]}]]
     (named? fields)))
 
 (defmethod struct-decl true
-  [[nm fields]]
-  [:struct nm (->> (mapv struct-field fields)
-                   (append [:struct-field
-                            {:docstring "Indicates which indexes are valid (`None` means \"all valid\"). Invalid indexes can occur on frames where a character is absent (ICs or 2v2 games)"}
-                            "validity"
-                            ["Option" "MutableBitmap"]]))])
+  [[nm {:keys [description fields]}]]
+  [:struct
+   {:docstring description}
+   nm
+   (->> (mapv struct-field fields)
+        (append [:struct-field
+                 {:docstring "Indicates which indexes are valid (`None` means \"all valid\"). Invalid indexes can occur on frames where a character is absent (ICs or 2v2 games)"}
+                 "validity"
+                 ["Option" "MutableBitmap"]]))])
 
 (defmethod struct-decl false
-  [[nm fields]]
-  [:tuple-struct nm (mapv tuple-struct-field fields)])
+  [[nm {:keys [description fields]}]]
+  [:tuple-struct
+   {:docstring description}
+   nm
+   (mapv tuple-struct-field fields)])
 
 (defn struct-impl
-  [[nm fields]]
+  [[nm {:keys [fields]}]]
   [:impl nm [(with-capacity-fn fields)
              (len-fn fields)
              (push-null-fn fields)

gen/src/peppi_codegen/frame/transpose.clj

@@ -18,11 +18,11 @@
      ver (conj ["Option"]))])
 
 (defmulti struct-decl
-  (fn [[nm fields]]
+  (fn [[nm {:keys [fields]}]]
     (named? fields)))
 
 (defmethod struct-decl true
-  [[nm fields]]
+  [[nm {:keys [fields]}]]
   [:struct
    {:attrs {:derive ["PartialEq" "Clone" "Copy" "Debug", "Default"]}}
    nm
@@ -31,7 +31,7 @@
         (mapv struct-field))])
 
 (defmethod struct-decl false
-  [[nm fields]]
+  [[nm {:keys [fields]}]]
   [:tuple-struct
    {:attrs {:derive ["PartialEq" "Clone" "Copy" "Debug", "Default"]}}
    nm

src/frame/immutable/mod.rs

@@ -166,9 +166,10 @@ impl fmt::Debug for Frame {
 	}
 }
 
+/// Information about the end of the game.
 #[derive(Debug)]
 pub struct End {
-	/// Index of the latest frame which is guaranteed not to happen again (rollback)
+	/// *Added: v3.7* Index of the latest frame which is guaranteed not to happen again (rollback)
 	pub latest_finalized_frame: Option<PrimitiveArray<i32>>,
 	/// Indicates which indexes are valid (`None` means "all valid"). Invalid indexes can occur on frames where a character is absent (ICs or 2v2 games)
 	pub validity: Option<Bitmap>,
@@ -191,6 +192,7 @@ impl From<mutable::End> for End {
 	}
 }
 
+/// An active item (includes projectiles).
 #[derive(Debug)]
 pub struct Item {
 	/// Item type
@@ -209,11 +211,11 @@ pub struct Item {
 	pub timer: PrimitiveArray<f32>,
 	/// Unique, serial ID per item spawned
 	pub id: PrimitiveArray<u32>,
-	/// Miscellaneous item state
+	/// *Added: v3.2* Miscellaneous item state
 	pub misc: Option<ItemMisc>,
-	/// Port that owns the item (-1 when unowned)
+	/// *Added: v3.6* Port that owns the item (-1 when unowned)
 	pub owner: Option<PrimitiveArray<i8>>,
-	/// Inherited instance ID of the owner (0 when unowned)
+	/// *Added: v3.16* Inherited instance ID of the owner (0 when unowned)
 	pub instance_id: Option<PrimitiveArray<u16>>,
 	/// Indicates which indexes are valid (`None` means "all valid"). Invalid indexes can occur on frames where a character is absent (ICs or 2v2 games)
 	pub validity: Option<Bitmap>,
@@ -256,6 +258,7 @@ impl From<mutable::Item> for Item {
 	}
 }
 
+/// Miscellaneous item state.
 #[derive(Debug)]
 pub struct ItemMisc(
 	pub PrimitiveArray<u8>,
@@ -281,6 +284,7 @@ impl From<mutable::ItemMisc> for ItemMisc {
 	}
 }
 
+/// 2D position.
 #[derive(Debug)]
 pub struct Position {
 	pub x: PrimitiveArray<f32>,
@@ -308,6 +312,9 @@ impl From<mutable::Position> for Position {
 	}
 }
 
+/// Post-frame update data, for making decisions about game states (such as computing stats).
+///
+/// Information is collected at the end of collision detection, which is the last consideration of the game engine.
 #[derive(Debug)]
 pub struct Post {
 	/// In-game character (can only change for Zelda/Sheik)
@@ -330,31 +337,31 @@ pub struct Post {
 	pub last_hit_by: PrimitiveArray<u8>,
 	/// Number of stocks remaining
 	pub stocks: PrimitiveArray<u8>,
-	/// Number of frames action state has been active. Can have a fractional component
+	/// *Added: v0.2* Number of frames action state has been active. Can have a fractional component
 	pub state_age: Option<PrimitiveArray<f32>>,
-	/// State flags
+	/// *Added: v2.0* State flags
 	pub state_flags: Option<StateFlags>,
-	/// Used for different things. While in hitstun, contains hitstun frames remaining
+	/// *Added: v2.0* Used for different things. While in hitstun, contains hitstun frames remaining
 	pub misc_as: Option<PrimitiveArray<f32>>,
-	/// Is the character airborne?
+	/// *Added: v2.0* Is the character airborne?
 	pub airborne: Option<PrimitiveArray<u8>>,
-	/// Ground ID the character last touched
+	/// *Added: v2.0* Ground ID the character last touched
 	pub ground: Option<PrimitiveArray<u16>>,
-	/// Number of jumps remaining
+	/// *Added: v2.0* Number of jumps remaining
 	pub jumps: Option<PrimitiveArray<u8>>,
-	/// L-cancel status (0 = none, 1 = successful, 2 = unsuccessful)
+	/// *Added: v2.0* L-cancel status (0 = none, 1 = successful, 2 = unsuccessful)
 	pub l_cancel: Option<PrimitiveArray<u8>>,
-	/// Hurtbox state (0 = vulnerable, 1 = invulnerable, 2 = intangible)
+	/// *Added: v2.1* Hurtbox state (0 = vulnerable, 1 = invulnerable, 2 = intangible)
 	pub hurtbox_state: Option<PrimitiveArray<u8>>,
-	/// Self-induced and knockback velocities
+	/// *Added: v3.5* Self-induced and knockback velocities
 	pub velocities: Option<Velocities>,
-	/// Hitlag frames remaining
+	/// *Added: v3.8* Hitlag frames remaining
 	pub hitlag: Option<PrimitiveArray<f32>>,
-	/// Animation the character is in
+	/// *Added: v3.11* Animation the character is in
 	pub animation_index: Option<PrimitiveArray<u32>>,
-	/// Instance ID of the player/item that last hit this player
+	/// *Added: v3.16* Instance ID of the player/item that last hit this player
 	pub last_hit_by_instance: Option<PrimitiveArray<u16>>,
-	/// Unique, serial ID for each new action state across all characters. Resets to 0 on death
+	/// *Added: v3.16* Unique, serial ID for each new action state across all characters. Resets to 0 on death
 	pub instance_id: Option<PrimitiveArray<u16>>,
 	/// Indicates which indexes are valid (`None` means "all valid"). Invalid indexes can occur on frames where a character is absent (ICs or 2v2 games)
 	pub validity: Option<Bitmap>,
@@ -427,6 +434,9 @@ impl From<mutable::Post> for Post {
 	}
 }
 
+/// Pre-frame update data, required to reconstruct a replay.
+///
+/// Information is collected right before controller inputs are used to figure out the character’s next action.
 #[derive(Debug)]
 pub struct Pre {
 	/// Random seed
@@ -449,11 +459,11 @@ pub struct Pre {
 	pub buttons_physical: PrimitiveArray<u16>,
 	/// Physical analog trigger positions (useful for IPM)
 	pub triggers_physical: TriggersPhysical,
-	/// Raw joystick x-position
+	/// *Added: v1.2* Raw joystick x-position
 	pub raw_analog_x: Option<PrimitiveArray<i8>>,
-	/// Damage taken (percent)
+	/// *Added: v1.4* Damage taken (percent)
 	pub percent: Option<PrimitiveArray<f32>>,
-	/// Raw joystick y-position
+	/// *Added: v3.15* Raw joystick y-position
 	pub raw_analog_y: Option<PrimitiveArray<i8>>,
 	/// Indicates which indexes are valid (`None` means "all valid"). Invalid indexes can occur on frames where a character is absent (ICs or 2v2 games)
 	pub validity: Option<Bitmap>,
@@ -500,11 +510,12 @@ impl From<mutable::Pre> for Pre {
 	}
 }
 
+/// Initialization data such as game mode, settings, characters & stage.
 #[derive(Debug)]
 pub struct Start {
 	/// Random seed
 	pub random_seed: PrimitiveArray<u32>,
-	/// Scene frame counter. Starts at 0, and increments every frame (even when paused)
+	/// *Added: v3.10* Scene frame counter. Starts at 0, and increments every frame (even when paused)
 	pub scene_frame_counter: Option<PrimitiveArray<u32>>,
 	/// Indicates which indexes are valid (`None` means "all valid"). Invalid indexes can occur on frames where a character is absent (ICs or 2v2 games)
 	pub validity: Option<Bitmap>,
@@ -529,6 +540,7 @@ impl From<mutable::Start> for Start {
 	}
 }
 
+/// Miscellaneous state flags.
 #[derive(Debug)]
 pub struct StateFlags(
 	pub PrimitiveArray<u8>,
@@ -556,6 +568,7 @@ impl From<mutable::StateFlags> for StateFlags {
 	}
 }
 
+/// Trigger state.
 #[derive(Debug)]
 pub struct TriggersPhysical {
 	pub l: PrimitiveArray<f32>,
@@ -583,6 +596,7 @@ impl From<mutable::TriggersPhysical> for TriggersPhysical {
 	}
 }
 
+/// Self-induced and knockback velocities.
 #[derive(Debug)]
 pub struct Velocities {
 	/// Self-induced x-velocity (airborne)
@@ -624,6 +638,7 @@ impl From<mutable::Velocities> for Velocities {
 	}
 }
 
+/// 2D velocity.
 #[derive(Debug)]
 pub struct Velocity {
 	pub x: PrimitiveArray<f32>,