Documentation for AssetPaths (#42)

* Documentation for AssetPaths

To address this HaxeFlixel/flixel-docs#265

* Address review issues

* address review issues

remove "more control" (will be in other doc)
add @see tags

* a note about where is this class from

* add left *

* aork around vscode md issues, shorten

---------

Co-authored-by: George FunBook <[email protected]>

default/source/AssetPaths.hx

@@ -1,4 +1,35 @@
 package;
 
+/**
+ * Helper class to access asset paths in a type-safe manner.
+ * 
+ * **NOTE:** this class is created when you use [`flixel template` command](https://haxeflixel.com/documentation/hello-world/#create-a-new-haxeflixel-project).
+ * 
+ * `AssetPaths`'s static fields are autogenerated by a neat [Haxe macro](http://haxe.org/manual/macro.html) 
+ * from the contents of [Project.xml's `<assets>`](https://lime.openfl.org/docs/project-files/xml-format/#assets) 
+ * tag, so you can easily reference them in your code. For example, rather than using the string path
+ * `"assets/sounds/mySound.wav"`, this class will generate `AssetPaths.mySound__wav` that you can pass into
+ * `FlxG.sound.play` calls.
+ * 
+ * Static fields available on `AssetPaths` will change whenever you add, remove, rename or move a file. 
+ * If you remove a file that is still referenced via `AssetPaths` you'll get a compile error, 
+ * this could be handy compared to using string paths, which only cause a runtime error if the file is missing.
+ * 
+ * ## Ignored Assets
+ * 
+ * In some cases `AssetPaths` will ignore your assets. The following cases will result in a warning
+ * at compile:
+ * 
+ * - **Invalid haxe fields**: For example, the file `assets/1.ogg` will give a warning since
+ * `1__ogg` is not a valid haxe field name.
+ * 
+ * - **Duplicate file names**: If you have assets with the same file names, whichever file is nested
+ * deeper or found later will be ignored. for example if you have assets `assets/hero/walk.png` and
+ * `assets/enemies/ranger/walk.png`, the latter will be ignored and the compiler will show a warning.
+ * 
+ * @see [FlxAssets.buildFileReferences()](https://api.haxeflixel.com/flixel/system/FlxAssets.html#buildFileReferences) is used by `AssetPaths` 
+ * and provides you some control on how `AssetPaths`'s fields are built.
+ * @see [Flixel 5.0.0 Migration guide - AssetPaths has less caveats](https://github.com/HaxeFlixel/flixel/wiki/Flixel-5.0.0-Migration-guide#assetpaths-has-less-caveats-2575)
+**/
 @:build(flixel.system.FlxAssets.buildFileReferences("assets", true))
 class AssetPaths {}