docs(api): added automatic API reference doc generation

docs/.vuepress/config.js

@@ -1,3 +1,5 @@
+const { sidebarTree } = require("../reference/config");
+
 module.exports = {
   title: "Joodle",
   description: "Documentation for Joodle, a Moodle Web Service API client for Node.js.",
@@ -20,7 +22,7 @@ module.exports = {
 
     lastUpdated: "Last Updated",
 
-    sidebar: {
+    sidebar: Object.assign({
       "/guide/": [
         {
           title: "Guide",
@@ -35,16 +37,7 @@ module.exports = {
           ]
         }
       ],
-      "/reference/": [
-        {
-          title: "API Reference",
-          collapsable: false,
-          children: [
-            ""
-          ]
-        }
-      ]
-    },
+    }, sidebarTree("Introduction")),
 
     smoothScroll: true,
 

docs/reference/README.md

@@ -1,5 +1 @@
-# Introduction
-
-The Joodle API Reference provides a detailed overview of the whole API provided by Joodle.
-
-This section is a WIP and should be available to read soon!
+### Welcome to API Reference

docs/reference/_index.md

@@ -0,0 +1,25 @@
+---
+title: Joodle
+---
+
+# Joodle
+
+<a name="Joodle"></a>
+
+## Joodle
+The main Joodle client class. Used to make API calls to Moodle's Web Services
+API.
+
+**Kind**: global class  
+<a name="new_Joodle_new"></a>
+
+### new Joodle(options, httpOptions)
+Initializes a new Joodle client instance for making API calls to Moodle's
+Web Services API.
+
+
+| Param | Description |
+| --- | --- |
+| options | The client's configuration options. |
+| httpOptions | HTTP configuration options to pass along to `got`. |
+

docs/reference/client.md

@@ -0,0 +1,24 @@
+---
+title: Client
+---
+
+# Client
+
+<a name="Client"></a>
+
+## Client
+A client that can send HTTP requests to a Moodle site's Web Services API.
+
+**Kind**: global class  
+<a name="new_Client_new"></a>
+
+### new Client(options, httpOptions)
+Initializes the client as well as the client's `got` instance so HTTP
+requests can be made.
+
+
+| Param | Description |
+| --- | --- |
+| options | The client's configuration options. |
+| httpOptions | HTTP configuration options to pass along to `got`. |
+

docs/reference/modules/_index.md

@@ -0,0 +1,55 @@
+---
+title: Module
+---
+
+# Module
+
+## Classes
+
+<dl>
+<dt><a href="#Module">Module</a></dt>
+<dd><p>Represents a collection of Moodle Web Services API functions.</p>
+</dd>
+</dl>
+
+## Functions
+
+<dl>
+<dt><a href="#handleResponse">handleResponse(body)</a></dt>
+<dd><p>Attempts to handle a JSON body returned by a call to Moodle&#39;s Web Services API.
+If the body contains an <code>exception</code> property, then the response is assumed to
+be erroneous, and a rejected Promise is returned.</p>
+</dd>
+</dl>
+
+<a name="Module"></a>
+
+## Module
+Represents a collection of Moodle Web Services API functions.
+
+**Kind**: global class  
+<a name="Module+get"></a>
+
+### module.get(wsfunction, searchParams)
+Performs a GET request to Moodle's Web Services API.
+
+**Kind**: instance method of [<code>Module</code>](#Module)  
+
+| Param | Description |
+| --- | --- |
+| wsfunction | The name of the Moodle Web Services API function to invoke. |
+| searchParams | Any additional GET parameters to include in the request. |
+
+<a name="handleResponse"></a>
+
+## handleResponse(body)
+Attempts to handle a JSON body returned by a call to Moodle's Web Services API.
+If the body contains an `exception` property, then the response is assumed to
+be erroneous, and a rejected Promise is returned.
+
+**Kind**: global function  
+
+| Param | Description |
+| --- | --- |
+| body | A JSON body returned by a Moodle API call. |
+

docs/reference/modules/auth/_index.md

@@ -0,0 +1,12 @@
+---
+title: auth
+---
+
+# auth
+
+<a name="AuthModule"></a>
+
+## AuthModule
+Functions relating to authentication in Moodle (specifically self-registration).
+
+**Kind**: global class  

docs/reference/modules/auth/email/_index.md

@@ -0,0 +1,36 @@
+---
+title: auth.email
+---
+
+# auth.email
+
+<a name="AuthEmailModule"></a>
+
+## AuthEmailModule
+Functions relating to Moodle's email-based self-registration.
+
+This module's function calls may throw errors if self registration is disabled.
+
+**Kind**: global class  
+
+* [AuthEmailModule](#AuthEmailModule)
+    * [.getSignUpSettings()](#AuthEmailModule+getSignUpSettings)
+    * [.signUpUser(user)](#AuthEmailModule+signUpUser)
+
+<a name="AuthEmailModule+getSignUpSettings"></a>
+
+### authEmailModule.getSignUpSettings()
+Get the sign-up required settings and profile fields.
+
+**Kind**: instance method of [<code>AuthEmailModule</code>](#AuthEmailModule)  
+<a name="AuthEmailModule+signUpUser"></a>
+
+### authEmailModule.signUpUser(user)
+Adds a new user to the site (pending user confirmation).
+
+**Kind**: instance method of [<code>AuthEmailModule</code>](#AuthEmailModule)  
+
+| Param | Description |
+| --- | --- |
+| user | The user to sign up. |
+

docs/reference/modules/core/_index.md

@@ -0,0 +1,12 @@
+---
+title: core
+---
+
+# core
+
+<a name="CoreModule"></a>
+
+## CoreModule
+Functions relating to core Moodle operations.
+
+**Kind**: global class  

docs/reference/modules/core/role/_index.md

@@ -0,0 +1,39 @@
+---
+title: core.role
+---
+
+# core.role
+
+<a name="RoleModule"></a>
+
+## RoleModule
+Functions for assigning and unassigning user roles.
+
+**Kind**: global class  
+
+* [RoleModule](#RoleModule)
+    * [.assignRoles(...assignments)](#RoleModule+assignRoles)
+    * [.unassignRoles(...unassignments)](#RoleModule+unassignRoles)
+
+<a name="RoleModule+assignRoles"></a>
+
+### roleModule.assignRoles(...assignments)
+Assigns roles to users.
+
+**Kind**: instance method of [<code>RoleModule</code>](#RoleModule)  
+
+| Param | Description |
+| --- | --- |
+| ...assignments | The roles to assign to users. |
+
+<a name="RoleModule+unassignRoles"></a>
+
+### roleModule.unassignRoles(...unassignments)
+Unassigns roles from users.
+
+**Kind**: instance method of [<code>RoleModule</code>](#RoleModule)  
+
+| Param | Description |
+| --- | --- |
+| ...unassignments | The roles to unassign from users. |
+

docs/reference/modules/core/user/_index.md

@@ -0,0 +1,144 @@
+---
+title: core.user
+---
+
+# core.user
+
+<a name="UserModule"></a>
+
+## UserModule
+Functions for user-related actions.
+
+**Kind**: global class  
+
+* [UserModule](#UserModule)
+    * [.agreeSitePolicy()](#UserModule+agreeSitePolicy)
+    * [.createUsers(...users)](#UserModule+createUsers)
+    * [.deleteUsers(...users)](#UserModule+deleteUsers)
+    * [.getCourseUserProfiles(...users)](#UserModule+getCourseUserProfiles)
+    * [.getPrivateFilesInfo(user)](#UserModule+getPrivateFilesInfo)
+    * [.getUserPreferences(name, user)](#UserModule+getUserPreferences)
+    * [.setUserPreferences(...preferences)](#UserModule+setUserPreferences)
+    * [.getUsers()](#UserModule+getUsers)
+    * [.getUsersByField(field, ...values)](#UserModule+getUsersByField)
+    * [.updateUserPicture(draftItemId, user)](#UserModule+updateUserPicture)
+    * [.deleteUserPicture(user)](#UserModule+deleteUserPicture)
+
+<a name="UserModule+agreeSitePolicy"></a>
+
+### userModule.agreeSitePolicy()
+Agrees to the Moodle site policy for the current
+web service user.
+
+**Kind**: instance method of [<code>UserModule</code>](#UserModule)  
+<a name="UserModule+createUsers"></a>
+
+### userModule.createUsers(...users)
+Creates users and adds them to the Moodle site.
+
+**Kind**: instance method of [<code>UserModule</code>](#UserModule)  
+
+| Param | Description |
+| --- | --- |
+| ...users | The users to create. |
+
+<a name="UserModule+deleteUsers"></a>
+
+### userModule.deleteUsers(...users)
+Deletes users from the Moodle site.
+
+**Kind**: instance method of [<code>UserModule</code>](#UserModule)  
+
+| Param | Description |
+| --- | --- |
+| ...users | The IDs of the users to delete. |
+
+<a name="UserModule+getCourseUserProfiles"></a>
+
+### userModule.getCourseUserProfiles(...users)
+Gets the course profiles for users.
+
+**Kind**: instance method of [<code>UserModule</code>](#UserModule)  
+
+| Param | Description |
+| --- | --- |
+| ...users | The users (comprising of user ID and course ID) to lookup. |
+
+<a name="UserModule+getPrivateFilesInfo"></a>
+
+### userModule.getPrivateFilesInfo(user)
+Returns general information about files in
+a user's private files area.
+
+**Kind**: instance method of [<code>UserModule</code>](#UserModule)  
+
+| Param | Description |
+| --- | --- |
+| user | The ID of the user to lookup file info on. If no ID is provided, the ID of the web service user is used. |
+
+<a name="UserModule+getUserPreferences"></a>
+
+### userModule.getUserPreferences(name, user)
+Returns user preferences for a Moodle user.
+
+**Kind**: instance method of [<code>UserModule</code>](#UserModule)  
+
+| Param | Description |
+| --- | --- |
+| name | The name of the preference to lookup. If no name is provided, all preferences are returned. |
+| user | The ID of the user to lookup preferences for. If no ID is provided, the ID of the web service user is used. |
+
+<a name="UserModule+setUserPreferences"></a>
+
+### userModule.setUserPreferences(...preferences)
+Sets user preferences for Moodle users.
+
+**Kind**: instance method of [<code>UserModule</code>](#UserModule)  
+
+| Param | Description |
+| --- | --- |
+| ...preferences | The preferences to set. |
+
+<a name="UserModule+getUsers"></a>
+
+### userModule.getUsers()
+Searches for users on the Moodle site that match
+the provided crtieria.
+
+**Kind**: instance method of [<code>UserModule</code>](#UserModule)  
+<a name="UserModule+getUsersByField"></a>
+
+### userModule.getUsersByField(field, ...values)
+Searches for users on the Moodle site that match
+a specific field value.
+
+**Kind**: instance method of [<code>UserModule</code>](#UserModule)  
+
+| Param | Description |
+| --- | --- |
+| field | The name of the field to search. |
+| ...values | The value to search users' fields for. |
+
+<a name="UserModule+updateUserPicture"></a>
+
+### userModule.updateUserPicture(draftItemId, user)
+Updates a user's profile picture.
+
+**Kind**: instance method of [<code>UserModule</code>](#UserModule)  
+
+| Param | Description |
+| --- | --- |
+| draftItemId | The ID of the draft file to use as the picture. |
+| user | The ID of the user to update the picture of. If no ID is provided, the ID of the web service user is used. |
+
+<a name="UserModule+deleteUserPicture"></a>
+
+### userModule.deleteUserPicture(user)
+Deletes a user's profile picture.
+
+**Kind**: instance method of [<code>UserModule</code>](#UserModule)  
+
+| Param | Description |
+| --- | --- |
+| user | The ID of the user to delete the picture of. If no ID is provided, the ID of the web service user is used. |
+