From 4c4ab71a47c741f78eb1f3516b43a8e19a8d0c89 Mon Sep 17 00:00:00 2001 From: Thomas Versteeg Date: Sat, 6 Apr 2024 16:58:16 +0200 Subject: [PATCH] docs(project): doc-comment every public struct and it's fields --- examples/boonga.json | 12 ++++-- src/lib.rs | 97 ++++++++++++++++++++++++++++++++++++++++---- 2 files changed, 98 insertions(+), 11 deletions(-) diff --git a/examples/boonga.json b/examples/boonga.json index 60f2956..c008534 100644 --- a/examples/boonga.json +++ b/examples/boonga.json @@ -20,10 +20,16 @@ ], "meta": { "app": "http://www.aseprite.org/", - "version": "1.1.6-dev", - "image": "boonga.png", + "version": "1.3.4-x64", "format": "RGBA8888", "size": { "w": 32, "h": 16 }, - "scale": "1" + "scale": "1", + "frameTags": [ + ], + "layers": [ + { "name": "Layer 1", "opacity": 255, "blendMode": "normal" } + ], + "slices": [ + ] } } diff --git a/src/lib.rs b/src/lib.rs index 0ee4e0d..238ddf2 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -16,33 +16,51 @@ //! This has been tested to work with aseprite 1.1.6 and 1.2.25; other //! versions have not been tested. +use std::ops::{Deref, DerefMut}; + use serde::{Deserialize, Serialize}; +/// 2D Rectangle with a position and a size. #[derive(Serialize, Deserialize, Debug, PartialEq, Eq, Clone, Copy)] pub struct Rect { + /// X coordinate. pub x: u32, + /// Y coordinate. pub y: u32, + /// Width. pub w: u32, + /// Height. pub h: u32, } +/// 2D point is space. #[derive(Serialize, Deserialize, Debug, PartialEq, Eq, Clone, Copy)] pub struct Point { + /// X coordinate. pub x: u32, + /// Y coordinate. pub y: u32, } +/// 2D size. #[derive(Serialize, Deserialize, Debug, PartialEq, Eq, Clone, Copy)] pub struct Dimensions { + /// Width. pub w: u32, + /// Height. pub h: u32, } +/// RGBA color. #[derive(PartialEq, Eq, Clone, Copy)] pub struct Color { + /// Red component. pub r: u8, + /// Green component. pub g: u8, + /// Blue component. pub b: u8, + /// Alpha component. pub a: u8, } @@ -53,15 +71,15 @@ impl std::fmt::Debug for Color { } } -impl serde::Serialize for Color { +impl Serialize for Color { fn serialize(&self, serializer: S) -> Result { format!("{:?}", self).serialize(serializer) } } -impl<'de> serde::Deserialize<'de> for Color { +impl<'de> Deserialize<'de> for Color { fn deserialize>(deserializer: D) -> Result { - let s: String = serde::Deserialize::deserialize(deserializer)?; + let s: String = Deserialize::deserialize(deserializer)?; if !s.starts_with('#') { Err(serde::de::Error::custom("color doesn't start with '#'")) } else if !s.len() == 7 { @@ -80,35 +98,51 @@ impl<'de> serde::Deserialize<'de> for Color { } } +/// A single frame as part of an animation. +/// +/// Contains timing and position information. #[derive(Serialize, Deserialize, Debug, PartialEq, Eq, Clone)] pub struct Frame { + /// Local path on disk. pub filename: String, + /// Data for this frame. #[serde(flatten)] pub data: FrameData, } -impl std::ops::Deref for Frame { +impl Deref for Frame { type Target = FrameData; fn deref(&self) -> &Self::Target { &self.data } } -impl std::ops::DerefMut for Frame { +impl DerefMut for Frame { fn deref_mut(&mut self) -> &mut Self::Target { &mut self.data } } +/// Data for a single frame as part of an animation. #[derive(Serialize, Deserialize, Debug, PartialEq, Eq, Clone)] #[serde(rename_all = "camelCase")] #[non_exhaustive] pub struct FrameData { + /// Rectangle on the sprite sheet for this sprite including padding. + /// + /// If `trimmed` is true and coordinates are zero this is exactly the same as `sprite_source_size`. pub frame: Rect, + /// Whether the sprite is rotated. pub rotated: bool, + /// Whether the sprite is trimmed, meaning whether empty pixels from the edge have been removed. pub trimmed: bool, + /// Trimmed rectangle on the sprite sheet for this sprite. + /// + /// If `trimmed` is true and coordinates are zero this is exactly the same as `frame`. pub sprite_source_size: Rect, + /// Actual frame size. pub source_size: Dimensions, + /// Frame duration in milliseconds. pub duration: u32, } @@ -149,28 +183,40 @@ fn deserialize_frames<'de, D: serde::Deserializer<'de>>(de: D) -> Result, } +/// Slice within the sprite. #[derive(Serialize, Deserialize, Debug, PartialEq, Eq, Clone)] #[serde(rename_all = "camelCase")] #[non_exhaustive] pub struct Slice { + /// Slice name. pub name: String, + /// Color with which the slice frame is displayed in Aseprite. pub color: Color, - pub data: Option, + /// List of slice keys. pub keys: Vec, + /// Custom data. + pub data: Option, } +/// Define the slice rectangle in a specific frame. #[derive(Serialize, Deserialize, Debug, PartialEq, Eq, Clone)] #[serde(rename_all = "camelCase")] #[non_exhaustive] pub struct SliceKey { + /// Frame number. pub frame: u32, + /// Outer slice bounds within the frame. pub bounds: Rect, + /// Pivot point within the slice. pub pivot: Option, + /// Center area of a nine-patch slice. pub center: Option, } +/// Sprite sheet metadata. #[derive(Serialize, Deserialize, Debug, PartialEq, Eq, Clone)] #[serde(rename_all = "camelCase")] #[non_exhaustive] pub struct Metadata { + /// Which application produced the sprite sheet. pub app: String, + /// Version of the application used to produce the sprite sheet. pub version: String, + /// Pixel format of the image file. pub format: String, + /// Pixel dimensions of the image file. pub size: Dimensions, - pub scale: String, // Surely this should be a number? + /// Scale of the image. + /// + /// Usually this is `1`. + /// + /// Unclear why this is a string, most likely to be compatible with the application the JSON is formatted after. + pub scale: String, + /// Relative path to the image file. + pub image: Option, + /// List of tags. + /// + /// Only present when "Meta: Tags" is enabled when exporting in Aseprite. #[serde(default)] pub frame_tags: Vec, + /// List of layers. + /// + /// Only present when "Meta: Layers" is enabled when exporting in Aseprite. #[serde(default)] pub layers: Vec, - pub image: Option, + /// List of slices. + /// + /// Only present when "Meta: Slices" is enabled when exporting in Aseprite. #[serde(default)] pub slices: Vec, } +/// Aseprite sprite sheet. +/// +/// Root type in an Aseprite JSON file. #[derive(Serialize, Deserialize, Debug, PartialEq, Eq, Clone)] #[serde(rename_all = "camelCase")] #[non_exhaustive] pub struct SpritesheetData { + /// List with sprite frame definitions. #[serde(deserialize_with = "deserialize_frames")] pub frames: Vec, + /// Meta data. pub meta: Metadata, }