@@ -1,3 +1,15 @@
1+/**
2+* Returns a connection to a Project:M36 database. The connection created relies on websockets and should therefore function from any modern web browser or node server. This API is asynchronous and callback-based.
3+* @param {string} protocol - Choose from "ws://" and "wss://". "wss" is the SSL-wrapped websockets protocol and should therefore be preferred.
4+* @param {string} host - The IP address or name of the host of the database.
5+* @param {string} path - The websocket path where the websocket server is bound. Unless the project-m36-websocket-server is proxied, this is ignored by the server.
6+* @param {string} dbname - The name of the remote database.
7+* @param {openCallback} openCallback - A function to call when the connection is successfully open and ready for queries.
8+* @param {errorCallback} errorCallback - A function called if the connection process encounters an error. This is not called for errors in the queries.
9+* @param {statusCallback} statusCallback - A function called with synchronous and asynchronous status updates such as query errors and query results.
10+* @param {promptCallback} promptCallback - A function called whenever prompt information such as the current schema name and current branch name (if any).
11+* @param {closeCallback} closeCallback - A function called once the connection is closed.
12+*/
113var ProjectM36Connection = function (protocol, host, port, path, dbname, openCallback, errorCallback, statusCallback, promptCallback, closeCallback) {
214 this.protocol = protocol;
315 this.host = host;
@@ -35,6 +47,13 @@ var ProjectM36Connection = function (protocol, host, port, path, dbname, openCal
3547 this.socket = socket;
3648}
3749
50+/**
51+* The argument returned as part of the 'statusCallback'. Typically, only one of the three status types is populated. These status updates are groups together so that the callback can feed into a user interface update function.
52+* @callback statusCallback
53+* @param {Object} relationResult - The status update containing a relation or null.
54+* @param {Object} acknowledgementresult - The status update containing an acknowledgement that the query was executed or null.
55+* @param {Object} errorResult - The status update containing the error information or null.
56+*/
3857var ProjectM36Status = function (relationResult, acknowledgementResult, errorResult)
3958{
4059 this.relation = relationResult;
@@ -84,11 +103,19 @@ ProjectM36Connection.prototype.handleResponse = function(message)
84103 }
85104}
86105
106+/**
107+* Executes a TutorialD string.
108+* @param {string} tutd - The TutorialD string.
109+*/
87110ProjectM36Connection.prototype.executeTutorialD = function(tutd)
88111{
89112 this.socket.send("executetutd:" + tutd);
90113}
91114
115+/**
116+* A utitily function which creates and returns a table element representing the relation.
117+* @param {object} - The relation returned from executing a relational expression.
118+*/
92119ProjectM36Connection.prototype.generateRelation = function(relation)
93120{
94121 var table = document.createElement("table");