Improving documentation

Author: Florian Krämer

docs/The-File-Object.md

@@ -49,7 +49,7 @@ Instead of calling `withFile()` you can also use `withResource()` to re-use an a
 
 You'll also have to add the (uu)id to the file object if your intended path for the file should require it. The same applies to other data that might be relevant for your path.
 
-## Serialization
+## Serialization & Saving the File Object
 
 The file object is serializable to json, and you can call `toArray()` on it to turn it into an array that you can either save in the structure you get or continue transforming it into whatever structure your persistence layer expects.
 

src/FileInterface.php

@@ -204,6 +204,9 @@ public function withFile(string $file): FileInterface;
  /**
  * Returns the path for the file in the storage system
  *
+ * This is probably most of the time a *relative* and not an absolute path
+ * to some root or container depending on the storage backend.
+ *
  * @return string
  */
  public function path(): string;
@@ -219,6 +222,9 @@ public function withPath(string $path): FileInterface;
  /**
  * Builds the path for this file
  *
+ * Keep in mind that the path will depend on the path builder configuration!
+ * The resulting path depends on the builder!
+ *
  * @param \Phauthentic\Infrastructure\Storage\PathBuilder\PathBuilderInterface $pathBuilder Path Builder
  * @return $this
  */
@@ -227,6 +233,9 @@ public function buildPath(PathBuilderInterface $pathBuilder): FileInterface;
  /**
  * Builds the URL for this file
  *
+ * Keep in mind that the URL will depend on the URL builder configuration!
+ * The resulting URL depends on the builder!
+ *
  * @param \Phauthentic\Infrastructure\Storage\UrlBuilder\UrlBuilderInterface $urlBuilder URL Builder
  * @return \Phauthentic\Infrastructure\Storage\FileInterface
  */
@@ -272,6 +281,9 @@ public function withUuid(string $uuid): FileInterface;
  /**
  * Filename
  *
+ * Be aware that the filename doesn't have to match the name of the actual
+ * file in the storage backend!
+ *
  * @param string $filename Filename
  * @return \Phauthentic\Infrastructure\Storage\FileInterface
  */