docs(project): doc-comment every public struct and it's fields

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": [
+ ]
  }
 }

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<S: serde::Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
  format!("{:?}", self).serialize(serializer)
  }
 }
 
-impl<'de> serde::Deserialize<'de> for Color {
+impl<'de> Deserialize<'de> for Color {
  fn deserialize<D: serde::Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
- 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<Vec<Fra
  de.deserialize_any(FramesVisitor)
 }
 
+/// Frame animation direction.
 #[derive(Serialize, Deserialize, Debug, PartialEq, Eq, Clone, Copy)]
 #[serde(rename_all = "camelCase")]
 #[non_exhaustive]
 pub enum Direction {
+ /// Normal animation direction.
  Forward,
+ /// Reversed animation direction.
  Reverse,
+ /// Animation is played forward and then backward and so on.
  Pingpong,
 }
 
+/// Tagged frame group.
+///
+/// This is a way to define a single animation within the sprite sheet.
 #[derive(Serialize, Deserialize, Debug, PartialEq, Eq, Clone)]
 #[serde(rename_all = "camelCase")]
 #[non_exhaustive]
 pub struct Frametag {
+ /// Tag name.
  pub name: String,
+ /// Frame start number.
  pub from: u32,
+ /// Frame end number.
  pub to: u32,
+ /// Animation direction.
  pub direction: Direction,
 }
 
 // These are listed at:
 // https://github.com/aseprite/aseprite/blob/51b038ac024dd99902ab5b0c0d61524c48856b93/src/doc/blend_mode.cpp#L18-L37
 
+/// Layer blend modes.
 #[derive(Serialize, Deserialize, Debug, PartialEq, Eq, Clone, Copy)]
 #[serde(rename_all = "snake_case")]
 #[non_exhaustive]
@@ -229,50 +275,85 @@ pub struct Layer {
  pub data: Option<String>,
 }
 
+/// 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<String>,
+ /// List of slice keys.
  pub keys: Vec<SliceKey>,
+ /// Custom data.
+ pub data: Option<String>,
 }
 
+/// 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<Point>,
+ /// Center area of a nine-patch slice.
  pub center: Option<Rect>,
 }
 
+/// 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<String>,
+ /// List of tags.
+ ///
+ /// Only present when "Meta: Tags" is enabled when exporting in Aseprite.
  #[serde(default)]
  pub frame_tags: Vec<Frametag>,
+ /// List of layers.
+ ///
+ /// Only present when "Meta: Layers" is enabled when exporting in Aseprite.
  #[serde(default)]
  pub layers: Vec<Layer>,
- pub image: Option<String>,
+ /// List of slices.
+ ///
+ /// Only present when "Meta: Slices" is enabled when exporting in Aseprite.
  #[serde(default)]
  pub slices: Vec<Slice>,
 }
 
+/// 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<Frame>,
+ /// Meta data.
  pub meta: Metadata,
 }