Merge remote branch 'origin/main'

Author: Andre-LA

docs/animation.md

@@ -1,17 +1,25 @@
-# nene/animation.nelua
-## Nene.AnimationRange (record)
+## animation
+
+Animation range type, used on Spritesheets
+
+### AnimationRange
 
 ```lua
-global Nene.AnimationRange = @record{
-  name: string,
-  fps: number,
-  from: usize,
-  to: usize,
+global AnimationRange = @record{
+  fps: number, -- frames per second of this animation
+  from: usize, -- first frame
+  to: usize,   -- last frame
 }
 ```
 
-## Nene.AnimationRange.__eq (function)
+Animation range type, used on Spritesheets
+
+### AnimationRange.__eq
 
 ```lua
-function Nene.AnimationRange.__eq(l: Nene.AnimationRange, r: Nene.AnimationRange): boolean
+function AnimationRange.__eq(l: AnimationRange, r: AnimationRange): boolean
 ```
+
+checks equality between animation ranges
+
+---

docs/audio.md

@@ -1,48 +1,142 @@
-# nene/audio.nelua
-## Nene.Sound (record)
+### Sound
 
 ```lua
-global Nene.Sound = @record{
-  _data: *Mix_Chunk,
+global Sound = @record{
+  _data: *Mix_Chunk, -- internal data, don't use it directly, use methods instead
   channel: integer, -- -1 when no channel is being used
 }
 ```
 
-## Nene.Sound:play (function)
+Wraps a (SDL_mixer) sound associated with a sound channel
+
+### Sound:get
 
 ```lua
-function Nene.Sound:play(loop: overload(boolean, integer, niltype))
+function Sound:get(): *Mix_Chunk
 ```
 
-## Nene.Sound:stop (function)
+It checks if the internal data is `nilptr` and then returns it.
+
+Related SDL_mixer documentation:
+* [Mix_Chunk](https://www.libsdl.org/projects/SDL_mixer/docs/SDL_mixer_85.html#SEC85)
+
+### Sound.load
 
 ```lua
-function Nene.Sound:stop()
+function Sound.load(filename: string): (Sound, boolean)
 ```
 
-## Nene.Sound:free (function)
+try to load a sound from a file.
+
+it returns:
+* `Sound` value, with internal data properly initialized if load is successful
+* a boolean which is `true` when the load succeeds.
+
+Related MixWrapper documentation:
+* [MixWrapper.load_wav](wrappers/mix.md#mixwrapperload_wav)
+
+### Sound:play
 
 ```lua
-function Nene.Sound:free()
+function Sound:play(loop: overload(boolean, integer, niltype))
 ```
 
-## Nene.Sound:stop_and_free (function)
+plays the loaded sound.
+* if `true` is passed on `loop` argument, the sound will loop forever;
+* if an `integer` is passed, the sound will loop `loop` times
+* if `nil` is passed, it will play only one time.
+
+When there is no sound loaded (that is, the internal data is `nilptr`), then this method
+does nothing, though it also `check`s if the internal is `nilptr` (unless the `nochecks` pragma is enabled)
+
+Related MixWrapper documentation:
+* [MixWrapper.play_channel](wrappers/mix.md#mixwrapperplay_channel)
+
+### Sound:stop
 
 ```lua
-function Nene.Sound:stop_and_free()
+function Sound:stop()
 ```
 
-## Nene.Music (record)
+Halts (stop, interrupt) the sound.
+
+Related MixWrapper documentation:
+* [MixWrapper.halt_channel](wrappers/mix.md#mixwrapperhalt_channel)
+
+### Sound:destroy
 
 ```lua
-global Nene.Music = @record{
+function Sound:destroy()
+```
+
+Destroy the sound and resets to zeroed state,
+
+> Note: It will first stop the sound and then free the sound's memory.
+
+Related MixWrapper documentation:
+* [MixWrapper.free_chunk](wrappers/mix.md#mixwrapperfree_chunk)
+
+### Music
+
+```lua
+global Music = @record{
   _data: *Mix_Music,
-  id: usize,
 }
 ```
 
-## Nene.Music:free (function)
+Wraps a (SDL_mixer) music
+
+### Music:get
+
+```lua
+function Music:get(): *Mix_Music
+```
+
+It checks if the internal data is `nilptr` and then returns it.
+
+Related SDL_mixer documentation:
+* [Mix_Music](https://www.libsdl.org/projects/SDL_mixer/docs/SDL_mixer_86.html#SEC86)
+
+### Music:play
+
+```lua
+function Music:play(loops: facultative(integer))
+```
+
+Plays the music (forever by default), note that this stops any playing music.
+
+You can also pass a `loop` argument, this makes the music loop `loop` times, also note that:
+* Passing `0` will make it play the music `0` times.
+* Passing `1` will make it only once.
+* Passing `-1` will make it looping forever, this is the default value.
+
+Related MixWrapper documentation:
+* [MixWrapper.play_music](wrappers/mix.md#mixwrapperplay_music)
+* [MixWrapper.halt_music](wrappers/mix.md#mixwrapperhalt_music)
+
+### Music.stop
 
 ```lua
-function Nene.Music:free()
+function Music.stop()
 ```
+
+Stops any playing music.
+
+Related MixWrapper documentation:
+* [MixWrapper.halt_music](wrappers/mix.md#mixwrapperhalt_music)
+* [MixWrapper.play_music](wrappers/mix.md#mixwrapperplay_music)
+
+### Music:destroy
+
+```lua
+function Music:destroy()
+```
+
+Destroy the music and resets to zeroed state.
+
+> Note: SDL_mixer first halts the music if it's playing, it also wait if it's still fading out.
+
+Related MixWrapper documentation:
+* [MixWrapper.free_music](wrappers/mix.md#mixwrapperfree_music)
+
+---

docs/camera.md

@@ -1,31 +1 @@
-# nene/camera.nelua
-## Nene.Camera (record)
-
-```lua
-global Nene.Camera = @record{
-  offset: Nene.Math.Vec2, -- should be on ([0, 1], [0, 1]) range
-  pos: Nene.Math.Vec2,
-}
-local Camera = Nene.Camera
-## Camera.value.is_camera = true
-```
-
-## Camera:set_offset (function)
-sets the offset vector of camera, it's {0.5, 0.5} by default, which  
-means that the objects will look  
-offset is how the camera centers on the screen, you probably want
-```lua
-function Camera:set_offset(offset: Nene.Math.Vec2)
-```
-
-## Camera:get_relative_pos (function)
-
-```lua
-function Camera:get_relative_pos(pos: Nene.Math.Vec2, screen_size: Nene.Math.Vec2): Nene.Math.Vec2
-```
-
-## Camera.new (function)
-
-```lua
-function Camera.new(pos: facultative(Nene.Math.Vec2)): Camera
-```
+---

docs/colors.md

@@ -1 +1,31 @@
-# nene/colors.nelua
+### Color
+
+```lua
+global Color = @SDL_Color
+```
+
+`Nene.Color` is an alias of `SDL_Color`, see it's documentation for more information.
+
+Related SDL documentation:
+* [SDL_Color](https://wiki.libsdl.org/SDL_Color)
+
+### Color.Palette
+
+```lua
+global Color.Palette: record{
+  black: Color,
+  white: Color,
+  red: Color,
+  green: Color,
+  blue: Color,
+  yellow: Color,
+  cyan: Color,
+  bg: Color,
+}
+```
+
+The general color pallete of Nene
+
+> Note: This is not related to [`SDL_Pallete`](https://wiki.libsdl.org/SDL_Palette) data structure.
+
+---