Add explanations of textures & player api usage, non-function sounds, and some minor touch-up of docs (#55)

doc/functions.md

@@ -1,13 +1,16 @@
 # Functions API
 
 ## `can_interact_with_node(player, pos)`
+
 returns `bool`
 
 checks for the ability to interact with a node via:
+
 * if a player
 * owner metadata key
-* protection_bypass
+* `protection_bypass`
 
 supports
+
 * minetest game default if present
-* else polyfill
+* else polyfill

doc/gameid.md

@@ -6,7 +6,7 @@ simply returns `minetest.get_game_info().id`
 
 ## minetest versions < 5.7
 
-approximates the gameid value via a hardcoded table of gameid=>modname 
+approximates the gameid value via a hardcoded table of gameid =\> modname,
 and then checks via `minetest.get_modpath()`. If it fails, it falls 
 back to using `xcompat_unknown_gameid` as the id. See the chart in the
-readme for which games are supported
+readme for which games are supported

doc/materials.md

@@ -1,11 +1,26 @@
 # Materials API
 
+## Usage
+
 The materials can be accessed anywhere in your mod with `xcompat.materials.material_name`.
 
-**Example**: `xcompat.materials.steel_ingot` returns the string of whichever item would closest represent the steel_ingot material in the current game.
+Behind the scenes, xcompat automatically changes the `xcompat.materials`
+variable to contain the correct materials for whichever game the mod is
+launched in. 
 
-Behind the scenes, the xcompat mod automatically changes the `xcompat.materials` variable to contain the correct materials for whichever game the mod is launched in. 
+## Game support
 
-See the [the support table in the readme](https://github.com/mt-mods/xcompat/tree/master?tab=readme-ov-file#directly-supported-games-and-mods) for an overview of supported games, and see the contents of `/src/materials/` for the supported materials and their names. 
+See the [the support table in the readme](https://github.com/mt-mods/xcompat/tree/master?tab=readme-ov-file#directly-supported-games-and-mods)
+for an overview of supported games, and see the contents of `/src/materials/`
+for the supported materials and their names. 
 
-**Example**: the `/src/materials/mineclonia.lua` file shows what the keys of `xcompat.materials` resolve to when playing Mineclonia, such as `xcompat.materials.steel_ingot` resolving to `mcl_core:iron_ingot`, and `xcompat.materials.mesa_crystal` resolving to `mcl_redstone:redstone` if supported.
+## Examples
+
+Writing `xcompat.materials.steel_ingot` returns the string of whichever item
+would closest represent the `steel_ingot` material in the current game.
+
+The `/src/materials/mineclonia.lua` file shows what the keys of
+`xcompat.materials` resolve to when playing Mineclonia, such as
+`xcompat.materials.steel_ingot` resolving to `mcl_core:iron_ingot`, and
+`xcompat.materials.mesa_crystal` resolving to `mcl_redstone:redstone` if
+supported.

doc/player.md

@@ -1,13 +1,21 @@
 # Player API
 
-mimic mtg player_api
+## Usage
 
-## NOTE
+The player api can be accessed in your script through `xcompat.player`.
 
-`xcompat.player.player_attached`
+This object mimics the `player_api` from Minetest Game, and should be a drop-in
+replacement in most cases. You should be able to simply replace instances
+of `player_api` in your script with `xcompat.player`.
 
-read/write from it is fine, looping over it is not as it is a proxy table. this
-would need lua5.2 __pairs/__ipairs metamethods support which i could polyfill
-for using https://stackoverflow.com/a/77354254 but didnt feel like doing at 
-this time. (luajit supports this via 5.2 extensions). additionally see issue: 
-https://github.com/minetest/minetest/issues/15133
+
+## Note on `xcompat.player.player_attached`
+
+Reading & writing to this object works, but because it's a proxy table it can't
+be looped over. 
+
+Looping over this object would require lua5.2 `__pairs`/`__ipairs` metamethod support.
+It would be possible to implement support for this through polyfill, 
+using [this method](https://stackoverflow.com/a/77354254) 
+(luajit supports this via 5.2 extensions), but it's not implemented as of now.
+Additionally see [this engine issue](https://github.com/minetest/minetest/issues/15133).

doc/sounds.md

@@ -1,5 +1,6 @@
 # Sound API
 
+
 ## Option 1: Agnostically depend
 
 You can do this by using a custom field in your node def instead of the `sounds` key.
@@ -22,7 +23,7 @@ where:
 
 ## Option 2: Hard depend
 
-add this mod to your mod.confs depends and directly call the sound_api as follows
+add this mod to your mod.confs depends and directly call the `sound_api` as follows
 
 ```lua
 minetest.register_node(nodename, {
@@ -32,4 +33,13 @@ minetest.register_node(nodename, {
 })
 ```
 
-* input: optional table to override some or all of returned values
+* input: optional table to override some or all of returned values
+
+
+## Note
+
+In some instances, when sounds are defined by strings and the sound doesn't
+belong to a block or anything mod-specific, xcompat may not be needed. E.g.
+the sound `"default_dig_choppy"` is accessed in the same way in both Mineclonia
+and Minetest Game, without xcompat.
+

doc/textures.md

@@ -1,3 +1,20 @@
 # Textures API
 
-consult `/src/texture/minetest.lua` at this time
+## Usage
+
+To use a texture in your mod, find the texture you want by looking at one of
+the files in `/src/texture`, and append its path to `xcompat.textures`.
+
+If a texture isn't supported for the current game, xcompat creates a solid 
+color texture using texture modifiers as a fallback, ensuring compatibility.
+
+## Example
+
+| Path                                | Result in Minetest Game      |
+| -                                   | -                            |
+| xcompat.textures.wool.white         | `"wool_white.png"`           |
+| xcompat.textures.wood.apple.planks  | `"default_wood.png"`         |
+| xcompat.textures.wood.jungle.leaves | `"default_jungleleaves.png"` |
+| xcompat.textures.glass.pane         | `"default_glass.png"`        |
+
+For games like Minetest and Mineclonia, see the file `/src/textures/minetest.lua`.