documentation update (thanks to Karim Gemayel)

1 files changed, 139 insertions, 102 deletions

diff --git a/src/mod_pubsub/pubsub.hrl b/src/mod_pubsub/pubsub.hrl
index ee21818b6..08f722672 100644
--- a/src/mod_pubsub/pubsub.hrl
+++ b/src/mod_pubsub/pubsub.hrl
@@ -35,112 +35,149 @@
 %% -------------------------------
 %% Pubsub types
 
-%%% @type host() = string().
-%%% <p><tt>host</tt> is the name of the PubSub service. For example, it can be
-%%% <tt>"pubsub.localhost"</tt>.</p>
-
-%%% @type pubsubNode() = [string()]. 
-%%% <p>A node is defined by a list of its ancestors. The last element is the name
-%%% of the current node. For example: 
-%%% ```["home", "localhost", "cromain", "node1"]'''</p>
-
-%%% @type stanzaError() = #xmlelement{}.
-%%% Example: 
-%%%    ```{xmlelement, "error",
-%%%        [{"code", Code}, {"type", Type}],
-%%%        [{xmlelement, Condition, [{"xmlns", ?NS_STANZAS}], []}]}'''
-
-%%% @type pubsubIQResponse() = #xmlelement{}.
-%%% Example:
-%%%    ```{xmlelement, "pubsub",
-%%%               [{"xmlns", ?NS_PUBSUB_EVENT}],
-%%%               [{xmlelement, "affiliations", [],
-%%%               []}]}'''
-
-%%% @type nodeOption() = {Option::atom(), Value::term()}.
-%%% Example:
-%%% ```{deliver_payloads, true}'''
-
-%%% @type nodeType() = string().
-%%% <p>The <tt>nodeType</tt> is a string containing the name of the PubSub
-%%% plugin to use to manage a given node. For example, it can be
-%%% <tt>"flat"</tt>, <tt>"hometree"</tt> or <tt>"blog"</tt>.</p>
-
-%%% @type jid() = #jid{
-%%%    user = string(),
-%%%    server = string(),
-%%%    resource = string(),
-%%%    luser = string(),
-%%%    lserver = string(),
-%%%    lresource = string()}.
-
-%%% @type ljid() = {User::string(), Server::string(), Resource::string()}.
-
-%%% @type affiliation() = none | owner | publisher | outcast.
-%%% @type subscription() = none | pending | unconfigured | subscribed.
-
-%%% internal pubsub index table
--record(pubsub_index, {index, last, free}).
-
-%%% @type pubsubNode() = #pubsub_node{
-%%%    nodeid = {Host::host(), Node::pubsubNode()},
-%%%    parentid = Node::pubsubNode(),
-%%%    nodeidx = int(),
-%%%    type = nodeType(),
-%%%    options = [nodeOption()]}.
-%%% <p>This is the format of the <tt>nodes</tt> table. The type of the table
-%%% is: <tt>set</tt>,<tt>ram/disc</tt>.</p>
-%%% <p>The <tt>parentid</tt> and <tt>type</tt> fields are indexed.</p>
-%%% nodeidx can be anything you want.
--record(pubsub_node, {nodeid,
-		      id,
-		      parents = [],
-		      type = "flat",
-		      owners = [],
-		      options = []
-		     }).
-
-%%% @type pubsubState() = #pubsub_state{
-%%%    stateid = {ljid(), nodeidx()},
-%%%    items = [ItemId::string()],
-%%%    affiliation = affiliation(),
-%%%    subscriptions = [subscription()]}.
-%%% <p>This is the format of the <tt>affiliations</tt> table. The type of the
-%%% table is: <tt>set</tt>,<tt>ram/disc</tt>.</p>
--record(pubsub_state, {stateid,
-		       items = [],
-		       affiliation = none,
-		       subscriptions = []
+%% @type host() = string().
+%% <p><tt>host</tt> is the name of the PubSub service. For example, it can be
+%% <tt><<"pubsub.localhost">></tt>.</p>
+
+%% @type nodeId() = binary().
+%% <p>A node is defined by a list of its ancestors. The last element is the name
+%% of the current node. For example: 
+%% ```<<"/home/localhost/user">>'''</p>
+
+%% @type nodeIdx() = integer().
+
+%% @type itemId() = string().
+
+%% @type subId() = string().
+
+%% @type payload() = [#xmlelement{} | #xmlcdata{}].
+
+%% @type stanzaError() = #xmlelement{}.
+%% Example: 
+%%    ```{xmlelement, "error",
+%%        [{"code", Code}, {"type", Type}],
+%%        [{xmlelement, Condition, [{"xmlns", ?NS_STANZAS}], []}]}'''
+%% @type pubsubIQResponse() = #xmlelement{}.
+%% Example:
+%%    ```{xmlelement, "pubsub",
+%%               [{"xmlns", ?NS_PUBSUB_EVENT}],
+%%               [{xmlelement, "affiliations", [],
+%%               []}]}'''
+
+%% @type nodeOption() = {Option, Value}.
+%%    Option = atom(),
+%%    Value = term().
+%% Example:
+%% ```{deliver_payloads, true}'''
+
+%% @type nodeType() = string().
+%% <p>The <tt>nodeType</tt> is a string containing the name of the PubSub
+%% plugin to use to manage a given node. For example, it can be
+%% <tt>"flat"</tt>, <tt>"hometree"</tt> or <tt>"blog"</tt>.</p>
+
+%% @type jid() = {jid, User, Server, Resource, LUser, LServer, LResource}.
+%%    User      = string(),
+%%    Server    = string(),
+%%    Resource  = string(),
+%%    LUser     = string(),
+%%    LServer   = string(),
+%%    LResource = string().
+
+%% @type ljid() = {User, Server, Resource}.
+%%     User     = string(),
+%%     Server   = string(),
+%%     Resource = string().
+
+%% @type affiliation() = 'none' | 'owner' | 'publisher' | 'publish-only' | 'member' | 'outcast'.
+
+%% @type subscription() = 'none' | 'pending' | 'unconfigured' | 'subscribed'.
+
+
+%% @type pubsubIndex() = {pubsub_index, Index, Last, Free}.
+%%    Index = atom(),
+%%    Last  = integer(),
+%%    Free  = [integer()].
+%% internal pubsub index table
+-record(pubsub_index,
+{
+  index,
+  last,
+  free
 }).
 
-%%% @type pubsubItem() = #pubsub_item{
-%%%    itemid = {ItemId::string(), nodeidx()},
-%%%    creation = {now(), ljid()},
-%%%    modification = {now(), ljid()},
-%%%    payload = XMLContent::string()}.
-%%% <p>This is the format of the <tt>published items</tt> table. The type of the
-%%% table is: <tt>set</tt>,<tt>disc</tt>,<tt>fragmented</tt>.</p>
--record(pubsub_item, {itemid,
-		      creation = {unknown,unknown},
-		      modification = {unknown,unknown},
-		      payload = []
-		     }).
-
-
-%% @type pubsubSubscription() = #pubsub_subscription{
-%%     subid     = string(),
-%%     state_key = {ljid(), pubsubNodeId()},
-%%     options   = [{atom(), term()}]
-%% }.
+%% @type pubsubNode() = {pubsub_node, NodeId, Id, Parents, Type, Owners, Options}.
+%%    NodeId  = {host() | ljid(), nodeId()},
+%%    Id      = nodeIdx(),
+%%    Parents = [nodeId()],
+%%    Type    = nodeType(),
+%%    Owners  = [ljid()],
+%%    Options = [nodeOption()].
+%% <p>This is the format of the <tt>nodes</tt> table. The type of the table
+%% is: <tt>set</tt>,<tt>ram/disc</tt>.</p>
+%% <p>The <tt>Parents</tt> and <tt>type</tt> fields are indexed.</p>
+%% <tt>id</tt> can be anything you want.
+-record(pubsub_node,
+{
+  nodeid,
+  id,
+  parents = [],
+  type    = "flat",
+  owners  = [],
+  options = []
+}).
+
+%% @type pubsubState() = {pubsub_state, StateId, Items, Affiliation, Subscriptions}.
+%%    StateId       = {ljid(), nodeIdx()},
+%%    Items         = [itemId()],
+%%    Affiliation   = affiliation(),
+%%    Subscriptions = [{subscription(), subId()}].
+%% <p>This is the format of the <tt>affiliations</tt> table. The type of the
+%% table is: <tt>set</tt>,<tt>ram/disc</tt>.</p>
+-record(pubsub_state,
+{
+  stateid,
+  items         = [],
+  affiliation   = 'none',
+  subscriptions = []
+}).
+
+%% @type pubsubItem() = {pubsub_item, ItemId, Creation, Modification, Payload}.
+%%    ItemId       = {itemId(), nodeIdx()},
+%%    Creation     = {now(), ljid()},
+%%    Modification = {now(), ljid()},
+%%    Payload      = payload().
+%% <p>This is the format of the <tt>published items</tt> table. The type of the
+%% table is: <tt>set</tt>,<tt>disc</tt>,<tt>fragmented</tt>.</p>
+-record(pubsub_item,
+{
+  itemid,
+  creation     = {'unknown','unknown'},
+  modification = {'unknown','unknown'},
+  payload      = []
+}).
+
+%% @type pubsubSubscription() = {pubsub_subscription, SubId, Options}.
+%%     SubId     = subId(),
+%%     Options   = [nodeOption()].
 %% <p>This is the format of the <tt>subscriptions</tt> table. The type of the
 %% table is: <tt>set</tt>,<tt>ram/disc</tt>.</p>
--record(pubsub_subscription, {subid, options}).
+-record(pubsub_subscription,
+{
+  subid,
+  options
+}).
 
-%% @type pubsubLastItem() = #pubsub_last_item{
-%%    nodeid    = nodeidx(),
-%%    itemid    = string(),
-%%    payload   = XMLContent::string()}.
+%% @type pubsubLastItem() = {pubsub_last_item, NodeId, ItemId, Creation, Payload}.
+%%    NodeId   = nodeIdx(),
+%%    ItemId   = itemId(),
+%%    Creation = {now(),ljid()},
+%%    Payload  = payload().
 %% <p>This is the format of the <tt>last items</tt> table. it stores last item payload
 %% for every node</p>
--record(pubsub_last_item, {nodeid, itemid, creation, payload}).
-
+-record(pubsub_last_item,
+{
+  nodeid,
+  itemid,
+  creation,
+  payload
+}).