Permalink
Browse files

[enhance] stdlib: Better documentation for the couchdb api.

  • Loading branch information...
Thomas Refis
Thomas Refis committed Sep 16, 2011
1 parent 0608df6 commit 0432628e90f2a437e54ca6aa87d09b4c414cdd1f
Showing with 20 additions and 3 deletions.
  1. +20 −3 stdlib/apis/couchdb/couchdb.opa
@@ -45,6 +45,8 @@ import stdlib.crypto
/**
* A record used to represent the path to a database.
+ * @param location The adress of the Couchdb server
+ * @param name The name of the table.
*/
type CouchDb.db_infos = {
location : string
@@ -182,7 +184,9 @@ CouchDb = {{
*/
Database = {{
+
/**
+ * Example: [list_all(auth, host)]
* @param host The location of the couchdb server.
*/
list_all(auth, host) = really_get(auth, host, "_all_dbs", {none})
@@ -251,6 +255,7 @@ CouchDb = {{
really_get(auth, the_db.location, "{the_db.name}/{doc_name}", {some = rev})
/**
+ * Example: [get_attachment(auth, dbinfos, docid, name)]
* @param name of the attached file.
*/
get_attachment(auth, the_db : CouchDb.db_infos, docname : CouchDb.doc_id,
@@ -273,6 +278,7 @@ CouchDb = {{
*/
/**
+ * Example: [post(auth, dbinfos, content)]
* @param content The json document to insert in the db
*/
post(auth, the_db : CouchDb.db_infos, document) : CouchDb.result =
@@ -292,19 +298,21 @@ CouchDb = {{
{success = {FormatedJson = (code, response)}}
/**
+ * Example: [put(auth, dbinfos, docid, document)]
+ * @param document The json document to insert in the db
+ *
* N.B. when updating, the document must contain a "_rev" field set to the
* last revision number of the document (which you can get with a head
* request, for example).
* Otherwise couchdb will say that there's a conflict.
- *
- * @param document −
*/
put(auth, the_db:CouchDb.db_infos, doc_name:CouchDb.doc_id, document) : CouchDb.result =
path = "{the_db.name}/{doc_name}"
content = Json.serialize(document)
put_request_unserialize_result(auth,the_db.location,path,"application/json",content)
/**
+ * Example: [put_attachment_at_revision(auth, dbinfos, docid, rev, name, mimetype, content)]
* @param name of the attached file
* @param mimetype of the attached file
* @param content of the attached file
@@ -316,6 +324,7 @@ CouchDb = {{
put_request_unserialize_result(auth, the_db.location, path, mimetype, content)
/**
+ * Example: [copy(auth, dbinfos, src, dst)]
* @param src id of the document to copy
* @param dst id of the new document
*/
@@ -359,6 +368,7 @@ CouchDb = {{
delete_request(auth, the_db.location, "{the_db.name}/{docid}?rev={rev}")
/**
+ * Example: [delete_attachment(auth, dbinfos, docid, rev, name)]
* @param name of the attachment
*/
delete_attachment(auth, the_db : CouchDb.db_infos, docid : CouchDb.doc_id,
@@ -373,18 +383,21 @@ CouchDb = {{
Misc = {{
/**
+ * Example: [get_root(auth, host)]
* @param host address of the couchdb server.
*/
get_root(auth : CouchDb.authentication_method, host) : CouchDb.result =
really_get(auth, host, "", {none})
/**
+ * Example: [get_active_tasks(auth, host)]
* @param host address of the couchdb server.
*/
get_active_tasks(a : CouchDb.authentication_method, h) : CouchDb.result =
really_get(a, h, "_active_tasks", {none})
/**
+ * Example: [get_log_tail(auth, host)]
* @param host address of the couchdb server.
* @param len an option of the number of bytes to retrieve
*/
@@ -398,11 +411,13 @@ CouchDb = {{
*/
Session = {{
+
/**
+ * Example: [log_in(host, username, password)]
* @param host address of the couchdb server.
* @param username −
* @param password −
- * @return The record {Login = ({Session = cookie}, jsonCtx)} when login succeed.
+ * @return [{Login = ({Session = cookie}, jsonCtx)}] when login succeed.
*/
log_in(host, user:string, pass:string) : CouchDb.result =
match gen_uri(host, "_session")
@@ -422,6 +437,7 @@ CouchDb = {{
| otherwise -> {failure = {Other = "{otherwise}"}}
/**
+ * Example: [log_out(auth, host)]
* @param host −
*/
log_out(auth : CouchDb.authentication_method, host) : CouchDb.result =
@@ -430,6 +446,7 @@ CouchDb = {{
| _ -> {failure = {NotLoggedIn}}
/**
+ * Example: [infos(auth, host]
* @param host −
*/
infos(auth : CouchDb.authentication_method, host) : CouchDb.result =

0 comments on commit 0432628

Please sign in to comment.