improve documentation (thanks to Karim Gemayel)

1 files changed, 47 insertions, 37 deletions

diff --git a/src/mod_pubsub/pubsub.hrl b/src/mod_pubsub/pubsub.hrl
index 08f722672..6fd40ecfa 100644
--- a/src/mod_pubsub/pubsub.hrl
+++ b/src/mod_pubsub/pubsub.hrl
@@ -35,9 +35,18 @@
 %% -------------------------------
 %% 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 hostPubsub() = string().
+%% <p><tt>hostPubsub</tt> is the name of the PubSub service. For example, it can be
+%% <tt>"pubsub.localhost"</tt>.</p>
+
+%% @type hostPEP() = {User, Server, Resource}
+%%     User     = string()
+%%     Server   = string()
+%%     Resource = [].
+%% <p>For example, it can be :
+%% ```{"bob", "example.org", []}'''.</p>
+
+%% @type host() = hostPubsub() | hostPEP().
 
 %% @type nodeId() = binary().
 %% <p>A node is defined by a list of its ancestors. The last element is the name
@@ -64,8 +73,8 @@
 %%               [{xmlelement, "affiliations", [],
 %%               []}]}'''
 
-%% @type nodeOption() = {Option, Value}.
-%%    Option = atom(),
+%% @type nodeOption() = {Option, Value}
+%%    Option = atom()
 %%    Value = term().
 %% Example:
 %% ```{deliver_payloads, true}'''
@@ -75,27 +84,28 @@
 %% 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(),
+%% @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(),
+%% @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 accessModel() = 'open' | 'presence' | 'roster' | 'authorize' | 'whitelist'.
 
-%% @type pubsubIndex() = {pubsub_index, Index, Last, Free}.
-%%    Index = atom(),
-%%    Last  = integer(),
+%% @type pubsubIndex() = {pubsub_index, Index, Last, Free}
+%%    Index = atom()
+%%    Last  = integer()
 %%    Free  = [integer()].
 %% internal pubsub index table
 -record(pubsub_index,
@@ -105,12 +115,12 @@
   free
 }).
 
-%% @type pubsubNode() = {pubsub_node, NodeId, Id, Parents, Type, Owners, Options}.
-%%    NodeId  = {host() | ljid(), nodeId()},
-%%    Id      = nodeIdx(),
-%%    Parents = [nodeId()],
-%%    Type    = nodeType(),
-%%    Owners  = [ljid()],
+%% @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>
@@ -126,10 +136,10 @@
   options = []
 }).
 
-%% @type pubsubState() = {pubsub_state, StateId, Items, Affiliation, Subscriptions}.
-%%    StateId       = {ljid(), nodeIdx()},
-%%    Items         = [itemId()],
-%%    Affiliation   = affiliation(),
+%% @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>
@@ -141,10 +151,10 @@
   subscriptions = []
 }).
 
-%% @type pubsubItem() = {pubsub_item, ItemId, Creation, Modification, Payload}.
-%%    ItemId       = {itemId(), nodeIdx()},
-%%    Creation     = {now(), ljid()},
-%%    Modification = {now(), ljid()},
+%% @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>
@@ -156,8 +166,8 @@
   payload      = []
 }).
 
-%% @type pubsubSubscription() = {pubsub_subscription, SubId, Options}.
-%%     SubId     = subId(),
+%% @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>
@@ -167,10 +177,10 @@
   options
 }).
 
-%% @type pubsubLastItem() = {pubsub_last_item, NodeId, ItemId, Creation, Payload}.
-%%    NodeId   = nodeIdx(),
-%%    ItemId   = itemId(),
-%%    Creation = {now(),ljid()},
+%% @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>