From 60505dfb0a6f743e5f5a592d9a2cd645398ebb68 Mon Sep 17 00:00:00 2001
From: Starbeamrainbowlabs <sbrl@starbeamrainbowlabs.com>
Date: Wed, 15 Jun 2016 19:20:03 +0100
Subject: [PATCH] Finish documentation.

---
 core.php                   |  4 ++++
 modules/feature-upload.php |  3 ++-
 modules/page-delete.php    |  2 +-
 modules/page-edit.php      | 26 ++++++++++++++++++++++++++
 modules/page-export.php    | 12 ++++++++++++
 modules/page-help.php      | 10 ++++++++++
 modules/page-list.php      | 18 ++++++++++++++++++
 modules/page-login.php     | 22 ++++++++++++++++++++++
 modules/page-logout.php    |  9 +++++++++
 modules/page-move.php      | 17 ++++++++++++++++-
 modules/page-update.php    | 17 ++++++++++++++++-
 modules/page-view.php      | 14 ++++++++++++++
 12 files changed, 150 insertions(+), 4 deletions(-)

diff --git a/core.php b/core.php
index 0eb0530..266d409 100644
--- a/core.php
+++ b/core.php
@@ -104,6 +104,10 @@ if($env->is_logged_in)
   * @apiDefine	UserNotModeratorError
   * @apiError	UserNotModeratorError	You weren't loggged in as a moderator before sending this request.
   */
+ /**
+  * @apiDefine	PageParameter
+  * @apiParam	{string}	page	The page to operate on.
+  */
 
 
 ////////////////////
diff --git a/modules/feature-upload.php b/modules/feature-upload.php
index 8bd4d03..585bd1b 100644
--- a/modules/feature-upload.php
+++ b/modules/feature-upload.php
@@ -11,6 +11,7 @@ register_module([
 		 * @api {get} ?action=upload Get a page to let you upload a file.
 		 * @apiName UploadFilePage
 		 * @apiGroup Upload
+		 * @apiPermission User
 		*/
 		
 		/**
@@ -205,7 +206,7 @@ register_module([
 		});
 		
 		/**
-		 * @api {get} ?action=preview Get a preview of a file
+		 * @api {get} ?action=preview&page={pageName}[&size={someSize}] Get a preview of a file
 		 * @apiName PreviewFile
 		 * @apiGroup Upload
 		 * @apiPermission Anonymous
diff --git a/modules/page-delete.php b/modules/page-delete.php
index 11c4a05..0a084fc 100644
--- a/modules/page-delete.php
+++ b/modules/page-delete.php
@@ -8,7 +8,7 @@ register_module([
 	"code" => function() {
 		global $settings;
 		/**
-		 * @api {post} ?action=upload Delete a file
+		 * @api {post} ?action=delete Delete a page
 		 * @apiDescription	Delete a page and all its associated data.
 		 * @apiName DeletePage
 		 * @apiGroup Page
diff --git a/modules/page-edit.php b/modules/page-edit.php
index f972e88..d2429e2 100644
--- a/modules/page-edit.php
+++ b/modules/page-edit.php
@@ -9,6 +9,17 @@ register_module([
 	"code" => function() {
 		global $settings;
 		
+		/**
+		 * @api {get} ?action=edit&page={pageName}[&newpage=yes]	Get an editing page
+		 * @apiDescription	Gets an editing page for a given page. If you don't have permission to edit the page in question, a view source pagee is returned instead.
+		 * @apiName			EditPage
+		 * @apiGroup		Page
+		 * @apiPermission	Anonymous
+		 * 
+		 * @apiUse PageParameter
+		 * @apiParam	{string}	newpage		Set to 'yes' if a new page is being created. Only affects a few bits of text here and there, and the HTTP response code recieved on success from the `save` action.
+		 */
+		
 		/*
 		 *           _ _ _
 		 *   ___  __| (_) |_
@@ -80,6 +91,21 @@ register_module([
 			exit(page_renderer::render_main("$title - $settings->sitename", $content));
 		});
 		
+		/**
+		 * @api {post} ?action=save&page={pageName}	Save an edit to a page.
+		 * @apiDescription	Saves an edit to a page. If an edit conflict is encountered, then a conflict resolution page is returned instead.
+		 * @apiName			EditPage
+		 * @apiGroup		Page
+		 * @apiPermission	Anonymous
+		 * 
+		 * @apiUse	PageParameter
+		 * @apiParam	{string}	newpage		GET only. Set to 'yes' to indicate that this is a new page that is being saved. Only affects the HTTP response code you recieve upon success.
+		 * @apiParam	{string}	content		POST only. The new content to save to the given filename.
+		 * @apiParam	{string}	tags		POST only. A comma-separated list of tags to assign to the current page. Will replace the existing list of tags, if any are present.
+		 * @apiParam	{string}	prev-content-hash	POST only. The hash of the original content before editing. If this hash is found to be different to a hash computed of the currentl saved content, a conflict resolution page will be returned instead of saving the provided content.
+		 * 
+		 * @apiError	UnsufficientPermissionError	You don't currently have sufficient permissions to save an edit.
+		 */
 		/*
 		 *
 		 *  ___  __ ___   _____
diff --git a/modules/page-export.php b/modules/page-export.php
index b515f21..031f788 100644
--- a/modules/page-export.php
+++ b/modules/page-export.php
@@ -8,6 +8,18 @@ register_module([
 	"code" => function() {
 		global $settings;
 		
+		/**
+		 * @api		{get}	?action=export	Export the all the wiki's content
+		 * @apiDescription	Export all the wiki's content. Please ask for permission before making a request to this URI. Note that some wikis may only allow moderators to export content.
+		 * @apiName		Export
+		 * @apiGroup	Utility
+		 * @apiPermission	Anonymous
+		 *
+		 * @apiError	InsufficientExportPermissionsError	The wiki has the export_allow_only_admins option turned on, and you aren't logged into a moderator account.
+		 * @apiError	CouldntOpenTempFileError		Pepperminty Wiki couldn't open a temporary file to send the compressed archive to.
+		 * @apiError	CouldntCloseTempFileError		Pepperminty Wiki couldn't close the temporary file to finish creating the zip archive ready for downloading.
+		 */
+		
 		/*
 		 * ███████ ██   ██ ██████   ██████  ██████  ████████ 
 		 * ██       ██ ██  ██   ██ ██    ██ ██   ██    ██    
diff --git a/modules/page-help.php b/modules/page-help.php
index 2cf6881..5ee9a63 100644
--- a/modules/page-help.php
+++ b/modules/page-help.php
@@ -8,6 +8,16 @@ register_module([
 	"code" => function() {
 		global $settings;
 		
+		/**
+		 * @api		{get}	?action=help[&dev=yes]	Get a help page
+		 * @apiDescription	Get a customised help page. This page will be slightly different for every wiki, depending on their name, settings, and installed modules.
+		 * @apiName		Help
+		 * @apiGroup	Utility
+		 * @apiPermission	Anonymous
+		 *
+		 * @apiParam	{string}	dev		Set to 'yes' to get a developer help page instead. The developer help page gives some general information about which modules and help page sections are registered, and other various (non-sensitive) settings.
+		 */
+		
 		/*
 		 * ██   ██ ███████ ██      ██████  
 		 * ██   ██ ██      ██      ██   ██ 
diff --git a/modules/page-list.php b/modules/page-list.php
index df3fb13..dfc544d 100644
--- a/modules/page-list.php
+++ b/modules/page-list.php
@@ -8,6 +8,14 @@ register_module([
 	"code" => function() {
 		global $settings;
 		
+		/**
+		 * @api		{get}	?action=list	List all pages 
+		 * @apiDescription	Gets a list of all the pages currently stored on the wiki.
+		 * @apiName		ListPages
+		 * @apiGroup	Page
+		 * @apiPermission	Anonymous
+		 */
+		
 		/*
 		 * ██      ██ ███████ ████████ 
 		 * ██      ██ ██         ██    
@@ -28,6 +36,16 @@ register_module([
 			exit(page_renderer::render_main("$title - $settings->sitename", $content));
 		});
 		
+		/**
+		 * @api		{get}	?action=list-tags[&tag=]	Get a list of tags or pages with a certain tag
+		 * @apiDescription	Gets a list of all tags on the wiki. Adding the `tag` parameter causes a list of pages with the given tag to be returned instead.
+		 * @apiName		ListTags
+		 * @apiGroup	Utility
+		 * @apiPermission	Anonymous
+		 * 
+		 * @apiParam	{string}	tag		Optional. If provided a list of all the pages with that tag is returned instead.
+		 */
+		
 		/*
 		 * ██      ██ ███████ ████████ ████████  █████   ██████  ███████ 
 		 * ██      ██ ██         ██       ██    ██   ██ ██       ██      
diff --git a/modules/page-login.php b/modules/page-login.php
index 6a6cfb1..ad15326 100644
--- a/modules/page-login.php
+++ b/modules/page-login.php
@@ -8,6 +8,16 @@ register_module([
 	"code" => function() {
 		global $settings;
 		
+		/**
+		 * @api		{get}	?action=login[&failed=yes][&returnto={someUrl}]	Get the login page
+		 * @apiName		Login
+		 * @apiGroup	Authorisation
+		 * @apiPermission	Anonymous
+		 * 
+		 * @apiParam	{string}	failed		Setting to yes causes a login failure message to be displayed above the login form.
+		 * @apiParam	{string}	returnto	Set to the url to redirect to upon a successful login.
+		 */
+		
 		/*
 		 * ██       ██████   ██████  ██ ███    ██
 		 * ██      ██    ██ ██       ██ ████   ██
@@ -41,6 +51,18 @@ register_module([
 			exit(page_renderer::render_main($title, $content));
 		});
 		
+		/**
+		 * @api		{post}	?action=checklogin	Perform a login
+		 * @apiName		CheckLogin
+		 * @apiGroup	Authorisation
+		 * @apiPermission	Anonymous
+		 * 
+		 * @apiParam	{string}	user		The user name to login with.
+		 * @apiParam	{string}	password	The password to login with.
+		 * @apiParam	{string}	returnto	The URL to redirect to upon a successful login.
+		 *
+		 * @apiError	InvalidCredentialsError	The supplied credentials were invalid. Note that this error is actually a redirect to ?action=login&failed=yes (with the returnto parameter appended if you supplied one)
+		 */
 		
 		/*
  		 * ██████ ██   ██ ███████  ██████ ██   ██
diff --git a/modules/page-logout.php b/modules/page-logout.php
index 03d3c88..41eb493 100644
--- a/modules/page-logout.php
+++ b/modules/page-logout.php
@@ -6,6 +6,15 @@ register_module([
 	"description" => "Adds an action to let users user out. For security reasons it is wise to add this module since logging in automatically opens a session that is valid for 30 days.",
 	"id" => "page-logout",
 	"code" => function() {
+		
+		/**
+		 * @api		{post}	?action=logout	Logout
+		 * @apiDescription	Logout. Make sure that your bot requests this URL when it is finished - this call not only clears your cookies but also clears the server's session file as well. Note that you can request this when you are already logged out and it will completely wipe your session on the server.
+		 * @apiName		Logout
+		 * @apiGroup	Authorisation
+		 * @apiPermission	Anonymous
+		 */
+		
 		/*
 		 * ██       ██████   ██████   ██████  ██    ██ ████████ 
 		 * ██      ██    ██ ██       ██    ██ ██    ██    ██    
diff --git a/modules/page-move.php b/modules/page-move.php
index 6832ba7..c2aa6aa 100644
--- a/modules/page-move.php
+++ b/modules/page-move.php
@@ -8,6 +8,21 @@ register_module([
 	"code" => function() {
 		global $settings;
 		
+		/**
+		 * @api		{get}	?action=move[new_name={newPageName}]	Move a page
+		 * @apiName		Move
+		 * @apiGroup	Page
+		 * @apiPermission	Moderator
+		 * 
+		 * @apiParam	{string}	new_name	The new name to move the page to. If not set a page will be returned containing a move page form.
+		 *
+		 * @apiUse UserNotModeratorError
+		 * @apiError	EditingDisabledError	Editing is disabled on this wiki, so pages can't be moved.
+		 * @apiError	PageExistsAtDestinationError	A page already exists with the specified new name.
+		 * @apiError	NonExistentPageError		The page you're trying to move doesn't exist in the first place.
+		 * @apiError	PreExistingFileError		A pre-existing file on the server's file system was detected.
+		 */
+		
 		/*
 		 * ███    ███  ██████  ██    ██ ███████ 
 		 * ████  ████ ██    ██ ██    ██ ██      
@@ -109,7 +124,7 @@ register_module([
 		});
 		
 		// Register a help section
-		add_help_section("60-move", "Moving Pages", "<p>If you are logged in as an adminitrator, then you have the power to move pages. To do this, click &quot;Delete&quot; in the &quot;More...&quot; menu when browsing the pge you wish to move. Type in the new name of the page, and then click &quot;Move Page&quot;.</p>");
+		add_help_section("60-move", "Moving Pages", "<p>If you are logged in as an administrator, then you have the power to move pages. To do this, click &quot;Delete&quot; in the &quot;More...&quot; menu when browsing the pge you wish to move. Type in the new name of the page, and then click &quot;Move Page&quot;.</p>");
 	}
 ]);
 
diff --git a/modules/page-update.php b/modules/page-update.php
index b346398..88aa444 100644
--- a/modules/page-update.php
+++ b/modules/page-update.php
@@ -6,6 +6,21 @@ register_module([
 	"description" => "Adds an update page that downloads the latest stable version of Pepperminty Wiki. This module is currently outdated as it doesn't save your module preferences.",
 	"id" => "page-update",
 	"code" => function() {
+		
+		/**
+		 * @api		{get}	?action=move[do=yes]	Update the wiki
+		 * @apiDescription	Update the wiki by downloading  a new version of Pepperminty Wiki from the URL specified in the settings. Note that unless you change the url from it's default, all custom modules installed will be removed. **Note also that this plugin is currently out of date. Use with extreme caution!**
+		 * @apiName			Update
+		 * @apiGroup		Utility
+		 * @apiPermission	Moderator
+		 * 
+		 * @apiParam	{string}	do		Set to 'yes' to actually do the upgrade. Omission causes a page asking whether an update is desired instead.
+		 * @apiParam	{string}	secret	The wiki's secret string that's stored in the settings.
+		 *
+		 * @apiUse UserNotModeratorError
+		 * @apiParam	InvalidSecretError	The supplied secret doesn't match up with the secret stored in the wiki's settings.
+		 */
+		
 		/*
 		 * ██    ██ ██████  ██████   █████  ████████ ███████ 
 		 * ██    ██ ██   ██ ██   ██ ██   ██    ██    ██      
@@ -22,7 +37,7 @@ register_module([
 				exit(page_renderer::render_main("Update - Error", "<p>You must be an administrator to do that.</p>"));
 			}
 			
-			if(!isset($_GET["do"]) or $_GET["do"] !== "true")
+			if(!isset($_GET["do"]) or $_GET["do"] !== "true" or $_GET["do"] !== "yes")
 			{
 				exit(page_renderer::render_main("Update $settings->sitename", "<p>This page allows you to update $settings->sitename.</p>
 				<p>Currently, $settings->sitename is using $settings->version of Pepperminty Wiki.</p>
diff --git a/modules/page-view.php b/modules/page-view.php
index 675e79e..8c7e990 100644
--- a/modules/page-view.php
+++ b/modules/page-view.php
@@ -6,6 +6,20 @@ register_module([
 	"description" => "Allows you to view pages. You really should include this one.",
 	"id" => "page-view",
 	"code" => function() {
+		/**
+		 * @api	{get}	?action=view[&page={pageName}][&revision=rid][&printable=yes]	View a page
+		 * @apiName			View
+		 * @apiGroup		Page
+		 * @apiPermission	Anonymous
+		 * 
+		 * @apiUse PageParameter
+		 * @apiParam	{number}	revision	The revision number to display.
+		 * @apiParam	{string}	printable	Set to 'yes' to get a printable version of the specified page instead.
+		 *
+		 * @apiError	NonExistentPageError	The page doesn't exist and editing is disabled in the wiki's settings. If editing isn't disabled, you will be redirected to the edit apge instead.
+		 * @apiError	NonExistentRevisionError	The specified revision was not found.
+		 */
+		
 		/*
 		 * ██    ██ ██ ███████ ██     ██ 
 		 * ██    ██ ██ ██      ██     ██ 
