improve docs, add examples

.github/workflows/ldoc.yml

@@ -21,4 +21,4 @@ jobs:
       uses: peaceiris/actions-gh-pages@v3
       with:
         github_token: ${{ secrets.GITHUB_TOKEN }}
-        publish_dir: ../out
+        publish_dir: docs

.gitignore

@@ -0,0 +1 @@
+docs

areas.lua

@@ -1,3 +1,5 @@
+---------
+-- area management
 
 local FILENAME = minetest.get_worldpath() .. "/bx_areas.json"
 local store = AreaStore()
@@ -38,6 +40,11 @@ end
 
 minetest.after(0, load_areas)
 
+--- registers an area
+-- @param pos1 the lower position
+-- @param pos2 the upper position
+-- @param data the data to save with
+-- @see area_storage.lua
 function blockexchange.register_area(pos1, pos2, data)
     local id = store:insert_area(pos1, pos2, "")
     cache[id] = {
@@ -48,6 +55,11 @@ function blockexchange.register_area(pos1, pos2, data)
     save_areas()
 end
 
+--- returns the first found area in that region
+-- @param pos1 the lower position
+-- @param pos2 the upper position
+-- @return the area data
+-- @see area_storage.lua
 function blockexchange.get_area(pos1, pos2)
     local list = store:get_areas_in_area(pos1, pos2, true, false)
     if not list then

config.ld

@@ -1,6 +1,8 @@
 project='blockexchange'
 title='Blockexchange minetest mod'
 description='cloud schematic exchanger'
-backtick_references=false
 file='.'
-dir='../out'
+dir='docs'
+examples={'examples'}
+format = 'markdown'
+readme = {'readme.md'}

examples/area_storage.lua

@@ -0,0 +1,33 @@
+-- luacheck: no unused
+
+local pos1 = { x=1, y=0, z=0 }
+local data = blockexchange.get_area(pos1)
+
+-- upload example data
+data = {
+    pos1 = { x=0, y=0, z=0 },
+    pos2 = { x=2, y=0, z=0 },
+    data = {
+        type = "upload",
+        schemaid = 99,
+        schemaname = "my_schema",
+        username = "MyAccount",
+        owner = "singleplayer",
+        origin = { x=0, y=0, z=0 }
+    }
+}
+
+-- download example data
+data = {
+    pos1 = { x=0, y=0, z=0 },
+    pos2 = { x=2, y=0, z=0 },
+    data = {
+        type = "download",
+        schemaid = 99,
+        schemaname = "my_schema",
+        username = "MyAccount",
+        owner = "singleplayer",
+        origin = { x=0, y=0, z=0 }
+    }
+}
+

examples/promise.lua

@@ -0,0 +1,27 @@
+-- luacheck: no unused
+-- Source: https://github.com/Billiam/promise.lua
+
+-- create a new promise
+local promise = Promise.new()
+
+-- register callbacks
+promise:next(function(value)
+    -- value == 2
+end):catch(function(err)
+    print("something went wrong: " .. err)
+end)
+
+-- resolve promise somewhere in an async code
+promise:resolve(2)
+
+-- example with the blockexchange info endpoint
+blockexchange.api.get_info():next(function(info)
+    info = {
+        api_version_major = 1,
+        api_version_minor = 1,
+        owner = "someone",
+        name = "central exchange"
+    }
+end):catch(function(err)
+    print("something went wrong: " .. err)
+end)