API Documentation about simple_protection HOT 7 OPEN

I'm working on a branch that documents functions & such using LDoc. I was wondering if you could help me with descriptions for some functions. This is some of what I have:

misc_functions.lua:

• table_contains(t, e)
  • Checks table for an item.
  • param t: Table definition
  • param e: Item to check for
• table_erase(t, e)
  • Removes an item from table.
  • param t: Table definition
  • param e: Item to be removed
• s_protect.can_access(pos, player_name)
  • Allows authorized users & mods to modify an area.
  • param pos: Coordinates of node to check access rights
  • param player_name: Player to check for access rights
• s_protect.get_location(pos_)
  • ???
  • param pos_: ???
• s_protect.get_area_bounds(pos_)
  • Retrieves protected area boundaries.
  • param pos_: Coordinates from which to identify protected area
• s_protect.get_center(pos1)
  • Retrieves center coordinates of protected area.
  • param pos1: Coordinates from which to identify protected area
• s_protect.load_config()
  • Loads configurations from file.

If you have time, I would appreciate feedback & corrections.

from simple_protection.

Thanks for your effort. The documentation looks quite good already. But for my part, I would prefer a separate Markdown documentation file to not clutter the Lua files more - basically the lua_api.txt style.
Hopefully I'll have some time tomorrow for this documentation.

from simple_protection.

Sure, that would be no problem (I think). I was attempting to do something similar with the mobs_redo mod. I created a separate file that contained all of the documentation to be parsed. I can do the same here.

from simple_protection.

Here is an example file with the documentation: api.ldoc (though, I think LDoc can parse straight markdown as well)

And here is the HTML output: API

from simple_protection.

Well so, the first version now exists here. I'm however afraid that LDoc won't be able reading this format, since it's not per-file and the parameters/return values are formatted differently to what I've seen on the project page.
The HTML version looks good, but it feels too over-engineered for a small API like this project provides.

from simple_protection.

So, I don't want to push this on you. The mod_api.txt looks nice & clean. I've seen other modders using that format or similar (is it documented somewhere?). But, I just wanted to show you a simplified layout using LDoc.

Instead of documenting each Lua script, I just grouped all functions, settings, items, etc. under individual links. It can currently be viewed (2018-07-26) on my page: Simple Protection API.

I won't bug you about it anymore. 😃

from simple_protection.

I want to suggest some new functions if possible.

• s_protect.on_set_square(func(pos, name))
  • Registers a function performed when an area is claimed.
  • Param pos: center pos or start pos of square
  • Param name: player name of owner
• s_protect.on_remove_square(func(pos, name))
  • Registers a function performed when an area is unclaimed.
  • Param pos: center pos or start pos of square
  • Param name: player name of owner

from simple_protection.