api docs work in progress.

git-svn-id: https://www.unprompted.com/svn/projects/tildefriends/trunk@4460 ed5197a5-7fde-0310-b194-c3ffbd925b24

apps/api/docs.js

@@ -1,6 +1,15 @@
 export const docs = {};
 
-docs.global = `# <span style="color: #aaf">App Globals</span>
+docs.global = `# Tilde Friends API Documentation
+
+Welcome to the Tilde Friends API documentation.
+
+ * [App Globals](#App_Globals)
+ * [Database Interface](#Database)
+ * [Remote Procedure Calls](#tfrpc)
+
+<a id="App_Globals"></a>
+## <span style="color: #aaf">App Globals</span>
 The following are functions and values exposed to all apps in their \`app.js\` or \`handler.js\`.  Most
 of these are asynchronous, returning a \`Promise\` that will be resolved when the call completes, unless
 noted otherwise.
@@ -8,11 +17,14 @@ noted otherwise.
 This is all a work in progess. These are liable to change without warning.  Feedback is welcome.
 
 The exposed functions in this API balance multiple competing needs:
- * The surface area of the exposed API ought to be fairlyl minimal.  If something can be implemented entirely app-side, that is
+ * The surface area of the exposed API ought to be fairly minimal.  If something can be implemented entirely app-side, that is
    generally preferred over building it into the core.
  * Everything is built on this API.  Ideally the admin app, the SSB app, and the editor all use standard API exposed to all
    apps, with appropriate permission guards in place making it so that only trusted apps do potentially destructive operations.
    There will be some things here that aren't necessarily general use to support what's required.
+
+If you are looking at the [Tilde Friends source code](https://www.tildefriends.net/~cory/releases/),
+the vast majority of these are implemented in \`src/*.js.c\` files, and exposed to apps via \`core/core.js\`.
 `;
 
 docs['core.user.credentials.session.name'] = `
@@ -54,6 +66,14 @@ Store a blob in the SSB database.
 *String* The stored blob ID.
 `;
 
+docs['ssb.blobGet()'] = `
+Fetches a blob from the database.
+### Parameters
+ * *String* **blob_id** The blob identifier to fetch (\`&....sha256\`).
+### Returns
+*ArrayBuffer* The blob data.
+`;
+
 docs['print()'] = `
 Log debug information both to the server's console and to the visiting user's browser console when possible.
 ### Parameters
@@ -74,7 +94,7 @@ Returns a database instance that is specific to the authenticated user and the g
  * *String* **package_name** The database package name.
  * *String* **key** The database key.
 ### Returns
- *Database* A database.
+*Database* A database.
 `;
 
 docs['shared_database()'] = `
@@ -82,10 +102,30 @@ Returns a database instance that is shared between all users of the app, determi
 ### Parameters
  * *String* **key** The database key.
 ### Returns
- *Database* A database.
+*Database* A database.
 `;
 
-docs['utf8Decode()'] =`
+docs['base64Decode()'] = `
+Decode a base64 string to bytes.
+
+Completes synchronously.
+### Parameters
+ * *String* value The base64-encoded string.
+### Returns
+*Uint8Array* The decoded bytes.
+`;
+
+docs['base64Encode()'] = `
+Encode bytes to a base64 string.
+
+Completes synchronously.
+### Parameters
+ * *Uint8Array* The bytes to encode.
+### Returns
+*String* The base64-encoded string.
+`;
+
+docs['utf8Decode()'] = `
 Decode UTF-8 bytes to a string.
 
 Completes synchronously.
@@ -95,7 +135,7 @@ Completes synchronously.
 *String* The value as a string.
 `;
 
-docs['utf8Encode()'] =`
+docs['utf8Encode()'] = `
 Encodes a string to UTF-8 bytes.
 
 Completes synchronously.
@@ -105,6 +145,37 @@ Completes synchronously.
 *Uint8Array* The encoded \`value\`.
 `;
 
+docs['setTimeout()'] = `
+Call a function after some delay.
+### Parameters
+ * *Function* **callback** The function to call.
+ * *Number* **timeout** Number of milliseconds to wait before calling the callback function.
+`;
+
+docs['parseHttpRequest()'] = `
+Parses an HTTP request.
+### Parameters
+ * *Uint8Array* **request** The request data.  Maybe be partial or contain extra data.  The return value will
+    indicate when and where it is complete.
+ * *Number* **last_length** The length of the data passed on a previous attempt for the same request, or 0 initially.
+### Returns
+ * *Integer* **-2** if the request is incomplete.
+ * *Integer* **-1** if the request could not be parsed.
+ * *Object* An object with **bytes_parsed**, **minor_version**, **path**, and **headers** fields on successful parse.
+`;
+
+docs['parseHttpResponse()'] = `
+Parses an HTTP response.
+### Parameters
+ * *Uint8Array* **response** The response data.  Maybe be partial or contain extra data.  The return value will
+    indicate when and where it is complete.
+ * *Number* **last_length** The length of the data passed on a previous attempt for the same response, or 0 initially.
+### Returns
+ * *Integer* **-2** if the response is incomplete.
+ * *Integer* **-1** if the response could not be parsed.
+ * *Object* An object with **bytes_parsed**, **minor_version**, **status**, **message**, and **headers** fields on successful parse.
+`;
+
 docs['sha1Digest()'] =`
 Calculates a SHA1 digest.
 
@@ -206,10 +277,11 @@ Removes an entry from the database if it exists.
 `;
 
 docs.tfrpc = `
-# <span style="color: #aaf">tfrpc</span>
+# <span style="color: #aaf" id="tfrpc">tfrpc</span>
 \`tfrpc.js\` is a small helper script that is available to be used to facilitate communication between parts of an application.
 
-\`tfrpc.js\` can be used to asynchronously make calls between the app in the browser and the app process on the server.
+\`tfrpc.js\` can be used to asynchronously make calls between the app code running in a sandboxed iframe in the browser
+and the app process on the server.
 
 From \`app.js\`:
 \`\`\`