Better specification for `Image::source` + example (#186)

assets/folder/tiled_relative_paths.tmx

+<?xml version="1.0" encoding="UTF-8"?>
+<map version="1.8" tiledversion="1.8.2" orientation="orthogonal" renderorder="right-down" width="16" height="16" tilewidth="32" tileheight="32" infinite="0" nextlayerid="3" nextobjectid="1">
+ <tileset firstgid="1" source="../tilesheet.tsx"/>
+ <layer id="1" name="Tile Layer 1" width="16" height="16">
+  <data encoding="csv">
+21,21,21,21,21,21,21,21,21,21,21,21,21,21,21,21,
+21,21,21,21,21,21,21,21,21,21,21,21,21,21,21,21,
+21,21,21,21,21,21,21,21,21,21,21,21,21,21,21,21,
+21,21,21,21,21,21,21,21,21,21,21,21,21,21,21,21,
+21,21,21,21,21,21,21,21,21,21,21,21,21,21,21,21,
+21,21,21,21,21,21,21,21,21,21,21,21,21,21,21,21,
+21,21,21,21,21,21,21,21,21,21,21,21,21,21,21,21,
+21,21,21,21,21,21,21,21,21,21,21,21,21,21,21,21,
+21,21,21,21,21,21,21,21,21,21,21,21,21,21,21,21,
+21,21,21,21,21,21,21,21,21,21,21,21,21,21,21,21,
+21,21,21,21,21,21,21,21,21,21,21,21,21,21,21,21,
+21,21,21,21,21,21,21,21,21,21,21,21,21,21,21,21,
+21,21,21,21,21,21,21,21,21,21,21,21,21,21,21,21,
+21,21,21,21,21,21,21,21,21,21,21,21,21,21,21,21,
+21,21,21,21,21,21,21,21,21,21,21,21,21,21,21,21,
+21,21,21,21,21,21,21,21,21,21,21,21,21,21,21,21
+</data>
+ </layer>
+ <imagelayer id="2" name="image">
+  <image source="../tilesheet.png" width="448" height="192"/>
+ </imagelayer>
+</map>

src/image.rs

@@ -7,14 +7,63 @@ use crate::{error::TiledError, properties::Color, util::*};
 /// A reference to an image stored somewhere within the filesystem.
 #[derive(Debug, PartialEq, Eq, Clone)]
 pub struct Image {
-    /// The filepath of the image.
+    /// The **uncanonicalized** filepath of the image, starting from the path given to load the file
+    /// this image is in. See the example for more details.
     ///
     /// ## Note
     /// The crate does not currently support embedded images (Even though Tiled
     /// does not allow creating maps with embedded image data, the TMX format does; [source])
     ///
+    /// Currently, the crate is not prepared to handle anything but OS paths. Using VFS is a hard
+    /// task that involves a lot of messy path manipulation. [Tracking issue]
+    ///
     /// [source]: https://doc.mapeditor.org/en/stable/reference/tmx-map-format/#image
+    /// [Tracking issue]: https://github.com/mapeditor/rs-tiled/issues/37
+    ///
+    /// ## Example
+    /// ```
+    /// use std::path::Path;
+    /// use std::fs::File;
+    /// use tiled::*;
+    ///
+    /// # fn main() -> Result<(), Box<dyn std::error::Error>> {
+    /// let map = Map::parse_file(
+    ///     "assets/folder/tiled_relative_paths.tmx",
+    ///     &mut FilesystemResourceCache::new(),
+    /// )?;
+    ///
+    /// let image_layer = match map
+    ///     .layers()
+    ///     .find(|layer| layer.name() == "image")
+    ///     .unwrap()
+    ///     .layer_type()
+    /// {
+    ///     LayerType::ImageLayer(layer) => layer,
+    ///     _ => panic!(),
+    /// };
+    ///
+    /// // Image layer has an image with the source attribute set to "../tilesheet.png"
+    /// // Given the information we gave to the `parse_file` function, the image source should be
+    /// // "assets/folder/../tilesheet.png". The filepath is not canonicalized.
+    /// let image_source = &image_layer.image().unwrap().source;
+    ///
+    /// assert_eq!(
+    ///     image_source,
+    ///     Path::new("assets/folder/../tilesheet.png")
+    /// );
+    ///
+    /// // If you are using the OS's filesystem, figuring out the real path of the image is as easy
+    /// // as canonicalizing the path. If you are using some sort of VFS, this task is much harder
+    /// // since std::path is meant to be used with the OS. This will be fixed in the future!
+    /// let image_source = image_source.canonicalize()?;
+    /// assert!(File::open(image_source).is_ok());
+    /// # Ok(())
+    /// # }
+    /// ```
+    /// Check the assets/tiled_relative_paths.tmx file at the crate root to see the structure of the
+    /// file this example is referring to.
     // TODO: Embedded images
+    // TODO: Figure out how to serve crate users paths in a better way
     pub source: PathBuf,
     /// The width in pixels of the image.
     pub width: i32,