Permalink
Browse files

edoc annotations in src comments

  • Loading branch information...
1 parent 6a61801 commit e7bc02e0db2b6795d970847bfa0b3d2eac10e5f3 Tony Hannan committed May 19, 2011
Showing with 103 additions and 103 deletions.
  1. +1 −1 README.md
  2. +35 −35 src/mongo.erl
  3. +12 −12 src/mongo_connect.erl
  4. +9 −9 src/mongo_cursor.erl
  5. +3 −3 src/mongo_protocol.erl
  6. +7 −7 src/mongo_query.erl
  7. +12 −12 src/mongo_replset.erl
  8. +5 −5 src/mongodb_app.erl
  9. +2 −2 src/mongodb_tests.erl
  10. +11 −11 src/mvar.erl
  11. +6 −6 src/pool.erl
View
@@ -67,7 +67,7 @@ If there are no errors in the sequence of operations then the result of the last
`mongo:find` returns a *cursor* holding the pending list of results, which are accessed using `mongo:next` to get the next result, and `mongo:rest` to get the remaining results. Either one throws `{cursor_expired, Cursor}` if the cursor was idle for more than 10 minutes. This exception is caught by `mongo:do` and returned as `{failure, {cursor_expired, Cursor}}`. `mongo:rest` also closes the cursor, otherwise you should close the cursor when finished using `mongo:close_cursor`.
-See the [*mongo* module](http://github.com/TonyGen/mongodb-erlang/blob/master/src/mongo.erl) for a description of all operations. A type specification is provided with each operation so you know the expected arguments and results. The spec line also has a comment if it performs a side-effect such as IO and what exceptions it may throw. No comment means it is a pure function. Also, see the [*bson* module](http://github.com/TonyGen/bson-erlang/blob/master/src/bson.erl) in the bson application for details on the document type and its value types.
+See the [*mongo*](http://github.com/TonyGen/mongodb-erlang/blob/master/src/mongo.erl) module for a description of all operations. A type specification is provided with each operation so you know the expected arguments and results. The spec line also has a comment if it performs a side-effect such as IO and what exceptions it may throw. No comment means it is a pure function. Also, see the [*bson* module](http://github.com/TonyGen/bson-erlang/blob/master/src/bson.erl) in the bson application for details on the document type and its value types.
### Administering
View
@@ -1,4 +1,4 @@
-% Top-level client interface to MongoDB
+%@doc Top-level client interface to MongoDB
-module (mongo).
-export_type ([maybe/1]).
@@ -40,15 +40,15 @@
-type connection() :: mongo_connect:connection().
-spec connect (host()) -> {ok, connection()} | {error, reason()}. % IO
-% Connect to given MongoDB server
+%@doc Connect to given MongoDB server
connect (Host) -> mongo_connect:connect (Host).
-spec disconnect (connection()) -> ok. % IO
-% Close connection to server
+%@doc Close connection to server
disconnect (Conn) -> mongo_connect:close (Conn).
-spec connect_factory (host()) -> pool:factory(connection()).
-% Factory for use with a connection pool. See pool module.
+%@doc Factory for use with a connection pool. See pool module.
connect_factory (Host) -> {Host, fun connect/1, fun disconnect/1, fun mongo_connect:is_closed/1}.
% Replica Set %
@@ -57,15 +57,15 @@ connect_factory (Host) -> {Host, fun connect/1, fun disconnect/1, fun mongo_conn
-type rs_connection() :: mongo_replset:rs_connection().
-spec rs_connect (replset()) -> rs_connection(). % IO
-% Create new cache of connections to replica set members starting with seed members. No connection attempted until rs_primary or rs_secondary_ok called.
+%@doc Create new cache of connections to replica set members starting with seed members. No connection attempted until rs_primary or rs_secondary_ok called.
rs_connect (Replset) -> mongo_replset:connect (Replset).
-spec rs_disconnect (rs_connection()) -> ok. % IO
-% Close cache of replset connections
+%@doc Close cache of replset connections
rs_disconnect (ReplsetConn) -> mongo_replset:close (ReplsetConn).
-spec rs_connect_factory (replset()) -> pool:factory(rs_connection()).
-% Factory for use with a rs_connection pool. See pool module.
+%@doc Factory for use with a rs_connection pool. See pool module.
rs_connect_factory (Replset) -> {Replset, fun (RS) -> RC = rs_connect (RS), {ok, RC} end, fun rs_disconnect/1, fun mongo_replset:is_closed/1}.
% Action %
@@ -85,7 +85,7 @@ rs_connect_factory (Replset) -> {Replset, fun (RS) -> RC = rs_connect (RS), {ok,
dbconn :: mongo_connect:dbconnection() }).
-spec do (write_mode(), read_mode(), connection() | rs_connection(), db(), action(A)) -> {ok, A} | {failure, failure()}. % IO
-% Execute mongo action under given write_mode, read_mode, connection, and db. Return action result or failure.
+%@doc Execute mongo action under given write_mode, read_mode, connection, and db. Return action result or failure.
do (WriteMode, ReadMode, Connection, Database, Action) -> case connection_mode (ReadMode, Connection) of
{error, Reason} -> {failure, {connection_failure, Reason}};
{ok, Conn} ->
@@ -103,7 +103,7 @@ do (WriteMode, ReadMode, Connection, Database, Action) -> case connection_mode (
end end.
-spec connection_mode (read_mode(), connection() | rs_connection()) -> {ok, connection()} | {error, reason()}. % IO
-% For rs_connection return appropriate primary or secondary connection
+%@doc For rs_connection return appropriate primary or secondary connection
connection_mode (_, Conn = {connection, _, _}) -> {ok, Conn};
connection_mode (master, RsConn = {rs_connection, _, _}) -> mongo_replset:primary (RsConn);
connection_mode (slave_ok, RsConn = {rs_connection, _, _}) -> mongo_replset:secondary_ok (RsConn).
@@ -120,7 +120,7 @@ connection_mode (slave_ok, RsConn = {rs_connection, _, _}) -> mongo_replset:seco
-type error_code() :: integer().
-spec write (mongo_query:write()) -> ok. % Action
-% Do unsafe unacknowledged fast write or safe acknowledged slower write depending on our context. When safe, throw write_failure if acknowledgment (getlasterror) reports error.
+%@doc Do unsafe unacknowledged fast write or safe acknowledged slower write depending on our context. When safe, throw write_failure if acknowledgment (getlasterror) reports error.
write (Write) ->
Context = get (mongo_action_context),
case Context #context.write_mode of
@@ -135,51 +135,51 @@ write (Write) ->
Code -> throw ({write_failure, Code, String}) end end end.
-spec insert (collection(), bson:document()) -> bson:value(). % Action
-% Insert document into collection. Return its '_id' value, which is auto-generated if missing.
+%@doc Insert document into collection. Return its '_id' value, which is auto-generated if missing.
insert (Coll, Doc) -> [Value] = insert_all (Coll, [Doc]), Value.
-spec insert_all (collection(), [bson:document()]) -> [bson:value()]. % Action
-% Insert documents into collection. Return their '_id' values, which are auto-generated if missing.
+%@doc Insert documents into collection. Return their '_id' values, which are auto-generated if missing.
insert_all (Coll, Docs) ->
Docs1 = lists:map (fun assign_id/1, Docs),
write (#insert {collection = Coll, documents = Docs1}),
lists:map (fun (Doc) -> bson:at ('_id', Doc) end, Docs1).
-spec assign_id (bson:document()) -> bson:document(). % IO
-% If doc has no '_id' field then generate a fresh object id for it
+%@doc If doc has no '_id' field then generate a fresh object id for it
assign_id (Doc) -> case bson:lookup ('_id', Doc) of
{_Value} -> Doc;
{} -> bson:append ({'_id', mongodb_app:gen_objectid()}, Doc) end.
-spec save (collection(), bson:document()) -> ok. % Action
-% If document has no '_id' field then insert it, otherwise update it and insert only if missing.
+%@doc If document has no '_id' field then insert it, otherwise update it and insert only if missing.
save (Coll, Doc) -> case bson:lookup ('_id', Doc) of
{} -> insert (Coll, Doc);
{Id} -> repsert (Coll, {'_id', Id}, Doc) end.
-spec replace (collection(), selector(), bson:document()) -> ok. % Action
-% Replace first document selected with given document.
+%@doc Replace first document selected with given document.
replace (Coll, Selector, Doc) -> update (false, false, Coll, Selector, Doc).
-spec repsert (collection(), selector(), bson:document()) -> ok. % Action
-% Replace first document selected with given document, or insert it if selection is empty.
+%@doc Replace first document selected with given document, or insert it if selection is empty.
repsert (Coll, Selector, Doc) -> update (true, false, Coll, Selector, Doc).
-spec modify (collection(), selector(), modifier()) -> ok. % Action
-% Update all documents selected using modifier
+%@doc Update all documents selected using modifier
modify (Coll, Selector, Mod) -> update (false, true, Coll, Selector, Mod).
-spec update (boolean(), boolean(), collection(), selector(), bson:document()) -> ok. % Action
update (Upsert, MultiUpdate, Coll, Sel, Doc) ->
write (#update {collection = Coll, upsert = Upsert, multiupdate = MultiUpdate, selector = Sel, updater = Doc}).
-spec delete (collection(), selector()) -> ok. % Action
-% Delete selected documents
+%@doc Delete selected documents
delete (Coll, Selector) ->
write (#delete {collection = Coll, singleremove = false, selector = Selector}).
-spec delete_one (collection(), selector()) -> ok. % Action
-% Delete first selected document.
+%@doc Delete first selected document.
delete_one (Coll, Selector) ->
write (#delete {collection = Coll, singleremove = true, selector = Selector}).
@@ -196,15 +196,15 @@ slave_ok (#context {read_mode = master}) -> false.
-type maybe(A) :: {A} | {}.
-spec find_one (collection(), selector()) -> maybe (bson:document()). % Action
-% Return first selected document, if any
+%@doc Return first selected document, if any
find_one (Coll, Selector) -> find_one (Coll, Selector, []).
-spec find_one (collection(), selector(), projector()) -> maybe (bson:document()). % Action
-% Return projection of first selected document, if any. Empty projection [] means full projection.
+%@doc Return projection of first selected document, if any. Empty projection [] means full projection.
find_one (Coll, Selector, Projector) -> find_one (Coll, Selector, Projector, 0).
-spec find_one (collection(), selector(), projector(), skip()) -> maybe (bson:document()). % Action
-% Return projection of Nth selected document, if any. Empty projection [] means full projection.
+%@doc Return projection of Nth selected document, if any. Empty projection [] means full projection.
find_one (Coll, Selector, Projector, Skip) ->
Context = get (mongo_action_context),
Query = #'query' {
@@ -213,19 +213,19 @@ find_one (Coll, Selector, Projector, Skip) ->
mongo_query:find_one (Context #context.dbconn, Query).
-spec find (collection(), selector()) -> cursor(). % Action
-% Return selected documents.
+%@doc Return selected documents.
find (Coll, Selector) -> find (Coll, Selector, []).
-spec find (collection(), selector(), projector()) -> cursor(). % Action
-% Return projection of selected documents. Empty projection [] means full projection.
+%@doc Return projection of selected documents. Empty projection [] means full projection.
find (Coll, Selector, Projector) -> find (Coll, Selector, Projector, 0).
-spec find (collection(), selector(), projector(), skip()) -> cursor(). % Action
-% Return projection of selected documents starting from Nth document. Empty projection means full projection.
+%@doc Return projection of selected documents starting from Nth document. Empty projection means full projection.
find (Coll, Selector, Projector, Skip) -> find (Coll, Selector, Projector, Skip, 0).
-spec find (collection(), selector(), projector(), skip(), batchsize()) -> cursor(). % Action
-% Return projection of selected documents starting from Nth document in batches of batchsize. 0 batchsize means default batch size. Negative batch size means one batch only. Empty projection means full projection.
+%@doc Return projection of selected documents starting from Nth document in batches of batchsize. 0 batchsize means default batch size. Negative batch size means one batch only. Empty projection means full projection.
find (Coll, Selector, Projector, Skip, BatchSize) ->
Context = get (mongo_action_context),
Query = #'query' {
@@ -236,23 +236,23 @@ find (Coll, Selector, Projector, Skip, BatchSize) ->
-type cursor() :: mongo_cursor:cursor().
-spec next (cursor()) -> maybe (bson:document()). % IO throws mongo_connect:failure() & mongo_cursor:expired() (this is a subtype of Action)
-% Return next document in query result cursor, if any.
+%@doc Return next document in query result cursor, if any.
next (Cursor) -> mongo_cursor:next (Cursor).
-spec rest (cursor()) -> [bson:document()]. % IO throws mongo_connect:failure() & mongo_cursor:expired() (this is a subtype of Action)
-% Return remaining documents in query result cursor.
+%@doc Return remaining documents in query result cursor.
rest (Cursor) -> mongo_cursor:rest (Cursor).
-spec close_cursor (cursor()) -> ok. % IO (IO is a subtype of Action)
-% Close cursor
+%@doc Close cursor
close_cursor (Cursor) -> mongo_cursor:close (Cursor).
-spec count (collection(), selector()) -> integer(). % Action
-% Count selected documents
+%@doc Count selected documents
count (Coll, Selector) -> count (Coll, Selector, 0).
-spec count (collection(), selector(), integer()) -> integer(). % Action
-% Count selected documents up to given max number; 0 means no max. Ie. stops counting when max is reached to save processing time.
+%@doc Count selected documents up to given max number; 0 means no max. Ie. stops counting when max is reached to save processing time.
count (Coll, Selector, Limit) ->
CollStr = atom_to_binary (Coll, utf8),
Command = if
@@ -266,7 +266,7 @@ count (Coll, Selector, Limit) ->
-type command() :: mongo_query:command().
-spec command (command()) -> bson:document(). % Action
-% Execute given MongoDB command and return its result.
+%@doc Execute given MongoDB command and return its result.
command (Command) ->
Context = get (mongo_action_context),
mongo_query:command (Context #context.dbconn, Command, slave_ok (Context)).
@@ -277,7 +277,7 @@ command (Command) ->
% List keys and whether ascending (1) or descending (-1). Eg. {x,1, y,-1}
-spec create_index (collection(), key_order()) -> ok. % Action
-% Create non-unique index on given keys in collection
+%@doc Create non-unique index on given keys in collection
create_index (Coll, KeyOrder) ->
create_index (Coll, KeyOrder, non_unique).
@@ -287,7 +287,7 @@ create_index (Coll, KeyOrder) ->
unique_dropdups. % Same as unique, but deletes docs with duplicate index value on index creation
-spec create_index (collection(), key_order(), index_uniqueness()) -> ok. % Action
-% Create index on given keys with given uniqueness
+%@doc Create index on given keys with given uniqueness
create_index (Coll, KeyOrder, Uniqueness) ->
create_index (Coll, KeyOrder, Uniqueness, gen_index_name (KeyOrder)).
@@ -302,7 +302,7 @@ gen_index_name (KeyOrder) ->
bson:doc_foldl (AsName, <<>>, KeyOrder).
-spec create_index (collection(), key_order(), index_uniqueness(), bson:utf8()) -> ok. % Action
-% Create index on given keys with given uniqueness and name
+%@doc Create index on given keys with given uniqueness and name
create_index (Coll, KeyOrder, Uniqueness, IndexName) ->
{Db, _} = (get (mongo_action_context)) #context.dbconn,
{Unique, DropDups} = case Uniqueness of
View
@@ -1,4 +1,4 @@
-% Thread-safe TCP connection to a MongoDB server with synchronous call and asynchronous send interface.
+%@doc Thread-safe TCP connection to a MongoDB server with synchronous call and asynchronous send interface.
-module (mongo_connect).
-export_type ([host/0, connection/0, dbconnection/0, failure/0]).
@@ -14,23 +14,23 @@
% Hostname and port. Port defaults to 27017 when missing
-spec host_port (host()) -> host().
-% Port explicitly filled in with defaut if missing
+%@doc Port explicitly filled in with defaut if missing
host_port ({Hostname, Port}) -> {hostname_string (Hostname), Port};
host_port (Hostname) -> {hostname_string (Hostname), 27017}.
-spec hostname_string (inet:hostname()) -> string().
-% Convert possible hostname atom to string
+%@doc Convert possible hostname atom to string
hostname_string (Name) when is_atom (Name) -> atom_to_list (Name);
hostname_string (Name) -> Name.
-spec show_host (host()) -> bson:utf8().
-% UString representation of host, ie. "Hostname:Port"
+%@doc UString representation of host, ie. "Hostname:Port"
show_host (Host) ->
{Hostname, Port} = host_port (Host),
bson:utf8 (Hostname ++ ":" ++ integer_to_list (Port)).
-spec read_host (bson:utf8()) -> host().
-% Interpret ustring as host, ie. "Hostname:Port" -> {Hostname, Port}
+%@doc Interpret ustring as host, ie. "Hostname:Port" -> {Hostname, Port}
read_host (UString) -> case string:tokens (bson:str (UString), ":") of
[Hostname] -> host_port (Hostname);
[Hostname, Port] -> {Hostname, list_to_integer (Port)} end.
@@ -43,29 +43,29 @@ read_host (UString) -> case string:tokens (bson:str (UString), ":") of
% Type not opaque to mongo:connection_mode/2
-spec connect (host()) -> {ok, connection()} | {error, reason()}. % IO
-% Create connection to given MongoDB server or return reason for connection failure.
+%@doc Create connection to given MongoDB server or return reason for connection failure.
connect (Host) -> try mvar:create (fun () -> tcp_connect (host_port (Host)) end, fun gen_tcp:close/1)
of VSocket -> {ok, {connection, host_port (Host), VSocket}}
catch Reason -> {error, Reason} end.
-spec conn_host (connection()) -> host().
-% Host this is connected to
+%@doc Host this is connected to
conn_host ({connection, Host, _VSocket}) -> Host.
-spec close (connection()) -> ok. % IO
-% Close connection.
+%@doc Close connection.
close ({connection, _Host, VSocket}) -> mvar:terminate (VSocket).
-spec is_closed (connection()) -> boolean(). % IO
-% Has connection been closed?
+%@doc Has connection been closed?
is_closed ({connection, _, VSocket}) -> mvar:is_terminated (VSocket).
-type dbconnection() :: {mongo_protocol:db(), connection()}.
-type failure() :: {connection_failure, connection(), reason()}.
-spec call (dbconnection(), [mongo_protocol:notice()], mongo_protocol:request()) -> mongo_protocol:reply(). % IO throws failure()
-% Synchronous send and reply. Notices are sent right before request in single block. Exclusive access to connection during entire call.
+%@doc Synchronous send and reply. Notices are sent right before request in single block. Exclusive access to connection during entire call.
call ({Db, Conn = {connection, _Host, VSocket}}, Notices, Request) ->
{MessagesBin, RequestId} = messages_binary (Db, Notices ++ [Request]),
Call = fun (Socket) ->
@@ -81,7 +81,7 @@ call ({Db, Conn = {connection, _Host, VSocket}}, Notices, Request) ->
exit: {noproc, _} -> throw ({connection_failure, Conn, closed}) end.
-spec send (dbconnection(), [mongo_protocol:notice()]) -> ok. % IO throws failure()
-% Asynchronous send (no reply). Don't know if send succeeded. Exclusive access to the connection during send.
+%@doc Asynchronous send (no reply). Don't know if send succeeded. Exclusive access to the connection during send.
send ({Db, Conn = {connection, _Host, VSocket}}, Notices) ->
{NoticesBin, _} = messages_binary (Db, Notices),
Send = fun (Socket) -> tcp_send (Socket, NoticesBin) end,
@@ -91,7 +91,7 @@ send ({Db, Conn = {connection, _Host, VSocket}}, Notices) ->
exit: {noproc, _} -> throw ({connection_failure, Conn, closed}) end.
-spec messages_binary (mongo_protocol:db(), [mongo_protocol:message()]) -> {binary(), mongo_protocol:requestid()}.
-% Binary representation of messages
+%@doc Binary representation of messages
messages_binary (Db, Messages) ->
Build = fun (Message, {Bin, _}) ->
RequestId = mongodb_app:next_requestid(),
Oops, something went wrong.

0 comments on commit e7bc02e

Please sign in to comment.