Documentation

Write some more documentation.

src/lua/db.lua

@@ -45,6 +45,8 @@ end
 --[[
 Provides an iterator that loops over results in an sql statement
 or throws an error, then resets the statement after the loop is done.
+Returned iterator returns varargs, so the values can be unpacked in-line in the
+for loop.
 ]]
 function db.sql_rows(stmnt)
 	if not stmnt then error("No statement",2) end

src/lua/endpoints/api_get.lua

@@ -15,6 +15,10 @@ function configure(...)
 	return oldconfigure(...)
 end
 
+--[[
+When a user is typing in the "tags" editbox when posting a story, suggest
+tags for them to include based on what they've typed so far.
+]]
 local function suggest_tags(req,data)
 	--[[
 	Prevent a malicious user from injecting '%' into the string

src/smr.c

@@ -105,12 +105,18 @@ do_lua(struct http_request *req, const char *name){
 	return KORE_RESULT_OK;
 }
 
+#define route(method, lua_method) \
+	int\
+	method(struct http_request *req){\
+		return do_lua(req,#lua_method);\
+	}
+
 /***
 Called at the endpoint <domain>/_paste.
-This method doesn't need any parameters for GET requests,
-and expects the following parametrs when POSTing:
-* title :: string
-* text :: string
+This method doesn't need any parameters for GET requests.
+This method expects the following for POST requests:
+* title :: string - story title
+* text :: string - text to put through markup
 * markup :: string - a valid markup type
 In addition to the normal assets, this page includes
 suggest_tags.js, which suggests tags that have been
@@ -119,26 +125,65 @@ submitted to the site before.
 @custom http_method GET POST
 @param http_request req The request to service
 ***/
-int
-post_story(struct http_request *req){
-	return do_lua(req,"paste");
-}
+route(post_story,"paste");
 
-int
-edit_story(struct http_request *req){
-	return do_lua(req,"edit");
-}
+/***
+Called at the endpoint <domain>/_edit.
+This method requires the following for GET requests:
+* story :: string - The url of the story to edit
+This method requires the following for POST requests:
+* title :: string - story title
+* text :: string - text to put through markup
+* markup :: string - a valid markup type
+* story :: string - the story we're editing
+In addition to normal assets, this page includes
+suggest_tags.js, which suggests tags that have been
+submitted to the site before.
+@function _G.edit
+@custom http_method GET POST
+@param http_request req The request to service
+***/
+route(edit_story, "edit");
 
-int
-edit_bio(struct http_request *req){
-	return do_lua(req,"edit_bio");
-}
+/***
+Called at the endpoint <domain>/_bio
+This method does not need any parameters for GET requests.
+This method requires the following for POST requests:
+* text :: string - The text to use as the author bio
+* author :: string - The author to modify
+If the logged in user does not match the author being
+modified, the user recives a 401 Unauthorized error.
+@function _G.edit_bio
+@custom http_method GET POST
+@param http_request req The request to service
+***/
+route(edit_bio, "edit_bio");
 
-int
-read_story(struct http_request *req){
-	return do_lua(req,"read");
-}
+/***
+Called at the endpoint <domain>/[^_]*
+This method does not require any parameters for GET requests, but may include:
+* load_comments :: 0 | 1 - Legacy parameter for loading comments
+* pwd :: [0-9a-f]{128} - If the post is marked as "unlisted", this parameter is
+ 	needed, if it is not passed, the user receives a 401 Unauthorized error.
+This method requires the following for POST requests:
+* text :: string - Comment text
+* postas :: string - The user to post as, if this is not "Anonymous", the
+	request must include a session cookie. If it does not, the user receives
+	a 401 Unauthorized error.
+* pwd :: [0-9a-f]{128} - Currently unused, but it's intended use is to validate
+	the user has the password for unlisted stories.
+@function _G.read
+@custom http_method GET POST
+@param http_request req The request to service
+***/
+route(read_story, "read");
 
+/***
+Called at the endpoint <domain>/_login
+This method does not requirei any parameters for GET requests.
+This method requiries the following for POST requests:
+* user :: [a-z0-9]{1,30} - The username to log in as
+* pass :: any - The passfile for this user
 int
 login(struct http_request *req){
 	return do_lua(req,"login");