Add API documentation

README.md

@@ -2,6 +2,11 @@
 
 An easy way to manage students in-game, with support for bulk actions and macros.
 
+An action is something that can be performed on a selection of students.
+You can use actions to move players, grant/revoke privs, and more.
+A list of built-in actions can be found below, however, you can
+add more actions using the API for this mod.
+
 Author: rubenwardy<br>
 License: LGPLv2.1+
 
@@ -14,12 +19,17 @@ First, make sure that you grant the `teacher` priv to any teachers like so:
 This allows them to access the classroom control panel, and exempts them from
 being included in actions.
 
-If using sfinv, open the Inventory and switch to the classroom tab.
+Open the Inventory and switch to the classroom tab.
+Only sfinv is supported currently.
 
 * The set of students that an action works on depends on the toggle bar at the top.
 	* **All:** apply the action to all students, but not teachers.
 	* **Group:** apply the action to all students in the currently selected group.
 	* **Selected:** apply the action only to the student that is currently selected.
+* You can changed the selected group using the tab header to the left.
+* You can manage groups using the New/Edit Group buttons in the
+  top-right.
+	* Use `>` to add the selected player to the group, `<` to remove.
 
 ### Actions
 
@@ -32,3 +42,83 @@ If using sfinv, open the Inventory and switch to the classroom tab.
 | Kick        | Remove from the server                                             |
 | Ban         | Permanently exclude from the server                                |
 | Audience    | Move to the crosshair location, spread out and facing you          |
+
+## API
+
+**WARNING:** This API is unstable, and breaking changes may be introduced before 1.0 is released.
+
+### Selectors
+
+A selector is a string which represents a selection of students.
+
+* `*` - All students
+* `group:<name>` - All students in group `<name>`
+* `user:<name>` - The user `<name>`
+
+### Actions
+
+```lua
+classroom.register_action("bring", {
+	-- Button text
+	title = "Bring",
+
+	-- Button tooltip
+	description = "Teleport players to your location",
+
+	-- Whether this should be restricted to online players
+	--  TODO: false isn't supported yet
+	online_required = true,
+
+	-- Function to perform the action
+	func = function(runner, names)
+		local pos = runner:get_pos()
+		for i=1, #names do
+			local player = minetest.get_player_by_name(names[i])
+			player:set_pos(pos)
+		end
+	end,
+
+	-- Custom keys are allowed
+})
+```
+
+### Group
+
+```lua
+{
+	-- Human-readable group name
+	name = name,
+
+	-- List of student names
+	students = {},
+
+	-- Custom keys are allowed
+}
+```
+
+### Methods
+
+* `classroom.get_students()`
+	* Get online students
+	* Returns list of player names
+* `classroom.get_group_students(name)`
+	* Get students in group, some students may be offline
+	* Returns list of player names
+* `classroom.get_students_except(excluded_students)`
+	* Get online students not in the list `excluded_students`
+	* Returns list of player names
+* `classroom.get_all_groups()`
+	* Returns table of `groupname -> group`
+* `classroom.get_group(name)`
+	* Returns group
+* `classroom.create_group(name)`
+	* Creates a group
+	* Returns the newly created group or nil if the name already exists
+* `classroom.add_student_to_group(group_name, student_name)`
+* `classroom.remove_student_from_group(group_name, student_name)`
+* `classroom.register_action(name, action_def)`
+* `classroom.get_actions()`
+	* Returns list of action defs
+* `classroom.get_students_by_selector(selector)`
+	* Gets online students using a selector.
+	* Returns list of player names