diff --git a/ChangeLog b/ChangeLog index 43948824d..55c50d891 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,7 @@ +2009-01-03 Badlop + + * src/*.erl: Fix EDoc comments + 2009-01-03 Christophe Romain * src/mod_pubsub/mod_pubsub.erl: deliver notification depending on @@ -24,7 +28,7 @@ 2008-12-24 Badlop * src/aclocal.m4: Fixes in configure script: fix - disable-disable_zlib and disable-pam; in case of problems, PAM + disable-ejabberd_zlib and disable-pam; in case of problems, PAM verification aborts with error instead of warning. (EJAB-787) * src/configure.ac: Likewise * src/configure: Likewise diff --git a/src/ejabberd_auth.erl b/src/ejabberd_auth.erl index d50278df1..70e6922ea 100644 --- a/src/ejabberd_auth.erl +++ b/src/ejabberd_auth.erl @@ -262,7 +262,7 @@ is_user_exists_in_other_modules(Module, User, Server) -> end, auth_modules(Server)--[Module]). %% @spec (User, Server) -> ok | error | {error, not_allowed} -%% Remove user. +%% @doc Remove user. %% Note: it may return ok even if there was some problem removing the user. remove_user(User, Server) -> R = lists:foreach( @@ -276,7 +276,7 @@ remove_user(User, Server) -> R. %% @spec (User, Server, Password) -> ok | not_exists | not_allowed | bad_request | error -%% Try to remove user if the provided password is correct. +%% @doc Try to remove user if the provided password is correct. %% The removal is attempted in each auth method provided: %% when one returns 'ok' the loop stops; %% if no method returns 'ok' then it returns the error message indicated by the last method attempted. diff --git a/src/ejabberd_auth_internal.erl b/src/ejabberd_auth_internal.erl index 1f545c273..fad6a57ed 100644 --- a/src/ejabberd_auth_internal.erl +++ b/src/ejabberd_auth_internal.erl @@ -244,7 +244,7 @@ is_user_exists(User, Server) -> end. %% @spec (User, Server) -> ok -%% Remove user. +%% @doc Remove user. %% Note: it returns ok even if there was some problem removing the user. remove_user(User, Server) -> LUser = jlib:nodeprep(User), @@ -257,7 +257,7 @@ remove_user(User, Server) -> ok. %% @spec (User, Server, Password) -> ok | not_exists | not_allowed | bad_request -%% Remove user if the provided password is correct. +%% @doc Remove user if the provided password is correct. remove_user(User, Server, Password) -> LUser = jlib:nodeprep(User), LServer = jlib:nameprep(Server), diff --git a/src/ejabberd_auth_odbc.erl b/src/ejabberd_auth_odbc.erl index d2843137e..61384daab 100644 --- a/src/ejabberd_auth_odbc.erl +++ b/src/ejabberd_auth_odbc.erl @@ -224,7 +224,7 @@ is_user_exists(User, Server) -> end. %% @spec (User, Server) -> ok | error -%% Remove user. +%% @doc Remove user. %% Note: it may return ok even if there was some problem removing the user. remove_user(User, Server) -> case jlib:nodeprep(User) of @@ -238,7 +238,7 @@ remove_user(User, Server) -> end. %% @spec (User, Server, Password) -> ok | error | not_exists | not_allowed -%% Remove user if the provided password is correct. +%% @doc Remove user if the provided password is correct. remove_user(User, Server, Password) -> case jlib:nodeprep(User) of error -> diff --git a/src/mod_pubsub/mod_pubsub.erl b/src/mod_pubsub/mod_pubsub.erl index 42ac390d7..4c5b661df 100644 --- a/src/mod_pubsub/mod_pubsub.erl +++ b/src/mod_pubsub/mod_pubsub.erl @@ -33,8 +33,8 @@ %%% This module uses version 1.12 of the specification as a base. %%% Most of the specification is implemented. %%% Functions concerning configuration should be rewritten. -%%% Code is derivated from the original pubsub v1.7, by Alexey Shchepin -%%% Code also inspired from the original PEP patch by Magnus Henoch +%%% Code is derivated from the original pubsub v1.7, by Alexey Shchepin (alexey at process-one.net) +%%% Code also inspired from the original PEP patch by Magnus Henoch (mange at freemail.hu) %%% TODO %%% plugin: generate Reply (do not use broadcast atom anymore) @@ -190,8 +190,9 @@ init([ServerHost, Opts]) -> nodetree = NodeTree, plugins = Plugins}}. -%% @spec (Host, Opts) -> Plugins -%% Host = mod_pubsub:host() Opts = [{Key,Value}] +%% @spec (Host, ServerHost, Opts) -> Plugins +%% Host = mod_pubsub:host() +%% Opts = [{Key,Value}] %% ServerHost = host() %% Key = atom() %% Value = term() @@ -1151,19 +1152,19 @@ handle_authorization_response(Host, From, To, Packet, XFields) -> %% @doc

Create new pubsub nodes

%%

In addition to method-specific error conditions, there are several general reasons why the node creation request might fail:

%%
    -%%
  • The service does not support node creation. -%%
  • Only entities that are registered with the service are allowed to create nodes but the requesting entity is not registered. -%%
  • The requesting entity does not have sufficient privileges to create nodes. -%%
  • The requested NodeID already exists. -%%
  • The request did not include a NodeID and "instant nodes" are not supported. +%%
  • The service does not support node creation.
    • +%%
  • Only entities that are registered with the service are allowed to create nodes but the requesting entity is not registered.
    • +%%
  • The requesting entity does not have sufficient privileges to create nodes.
    • +%%
  • The requested NodeID already exists.
    • +%%
  • The request did not include a NodeID and "instant nodes" are not supported.
    • %%
%%

ote: node creation is a particular case, error return code is evaluated at many places:

%%
    -%%
  • iq_pubsub checks if service supports node creation (type exists) -%%
  • create_node checks if instant nodes are supported -%%
  • create_node asks node plugin if entity have sufficient privilege -%%
  • nodetree create_node checks if nodeid already exists -%%
  • node plugin create_node just sets default affiliation/subscription +%%
  • iq_pubsub checks if service supports node creation (type exists)
    • +%%
  • create_node checks if instant nodes are supported
    • +%%
  • create_node asks node plugin if entity have sufficient privilege
    • +%%
  • nodetree create_node checks if nodeid already exists
    • +%%
  • node plugin create_node just sets default affiliation/subscription
    • %%
create_node(Host, ServerHost, Node, Owner, Type) -> create_node(Host, ServerHost, Node, Owner, Type, all, []). @@ -1274,9 +1275,9 @@ create_node(Host, ServerHost, Node, Owner, GivenType, Access, Configuration) -> %% @doc

Delete specified node and all childs.

%%

There are several reasons why the node deletion request might fail:

%%
    -%%
  • The requesting entity does not have sufficient privileges to delete the node. -%%
  • The node is the root collection node, which cannot be deleted. -%%
  • The specified node does not exist. +%%
  • The requesting entity does not have sufficient privileges to delete the node.
    • +%%
  • The node is the root collection node, which cannot be deleted.
    • +%%
  • The specified node does not exist.
    • %%
delete_node(_Host, [], _Owner) -> %% Node is the root @@ -1326,20 +1327,20 @@ delete_node(Host, Node, Owner) -> %% From = jid() %% JID = jid() %% @doc

Accepts or rejects subcription requests on a PubSub node.

-%% @see node_default:subscribe_node/5 %%

There are several reasons why the subscription request might fail:

%%
    -%%
  • The bare JID portions of the JIDs do not match. -%%
  • The node has an access model of "presence" and the requesting entity is not subscribed to the owner's presence. -%%
  • The node has an access model of "roster" and the requesting entity is not in one of the authorized roster groups. -%%
  • The node has an access model of "whitelist" and the requesting entity is not on the whitelist. -%%
  • The service requires payment for subscriptions to the node. -%%
  • The requesting entity is anonymous and the service does not allow anonymous entities to subscribe. -%%
  • The requesting entity has a pending subscription. -%%
  • The requesting entity is blocked from subscribing (e.g., because having an affiliation of outcast). -%%
  • The node does not support subscriptions. -%%
  • The node does not exist. +%%
  • The bare JID portions of the JIDs do not match.
    • +%%
  • The node has an access model of "presence" and the requesting entity is not subscribed to the owner's presence.
    • +%%
  • The node has an access model of "roster" and the requesting entity is not in one of the authorized roster groups.
    • +%%
  • The node has an access model of "whitelist" and the requesting entity is not on the whitelist.
    • +%%
  • The service requires payment for subscriptions to the node.
    • +%%
  • The requesting entity is anonymous and the service does not allow anonymous entities to subscribe.
    • +%%
  • The requesting entity has a pending subscription.
    • +%%
  • The requesting entity is blocked from subscribing (e.g., because having an affiliation of outcast).
    • +%%
  • The node does not support subscriptions.
    • +%%
  • The node does not exist.
    • %%
+%% @see node_default:subscribe_node/5 subscribe_node(Host, Node, From, JID) -> Subscriber = case jlib:string_to_jid(JID) of error -> {"", "", ""}; @@ -1411,7 +1412,7 @@ subscribe_node(Host, Node, From, JID) -> {result, Result} end. -%% @spec (Host, Noce, From, JID) -> {error, Reason} | {result, []} +%% @spec (Host, Noce, From, JID, SubId) -> {error, Reason} | {result, []} %% Host = host() %% Node = pubsubNode() %% From = jid() @@ -1421,12 +1422,12 @@ subscribe_node(Host, Node, From, JID) -> %% @doc

Unsubscribe JID from the Node.

%%

There are several reasons why the unsubscribe request might fail:

%%
    -%%
  • The requesting entity has multiple subscriptions to the node but does not specify a subscription ID. -%%
  • The request does not specify an existing subscriber. -%%
  • The requesting entity does not have sufficient privileges to unsubscribe the specified JID. -%%
  • The node does not exist. -%%
  • The request specifies a subscription ID that is not valid or current. -%% +%%
  • The requesting entity has multiple subscriptions to the node but does not specify a subscription ID.
    • +%%
  • The request does not specify an existing subscriber.
    • +%%
  • The requesting entity does not have sufficient privileges to unsubscribe the specified JID.
    • +%%
  • The node does not exist.
    • +%%
  • The request specifies a subscription ID that is not valid or current.
    • +%%
unsubscribe_node(Host, Node, From, JID, SubId) -> Subscriber = case jlib:string_to_jid(JID) of error -> {"", "", ""}; @@ -1449,12 +1450,12 @@ unsubscribe_node(Host, Node, From, JID, SubId) -> %%

The permission to publish an item must be verified by the plugin implementation.

%%

There are several reasons why the publish request might fail:

%%
    -%%
  • The requesting entity does not have sufficient privileges to publish. -%%
  • The node does not support item publication. -%%
  • The node does not exist. -%%
  • The payload size exceeds a service-defined limit. -%%
  • The item contains more than one payload element or the namespace of the root payload element does not match the configured namespace for the node. -%%
  • The request does not match the node configuration. +%%
  • The requesting entity does not have sufficient privileges to publish.
    • +%%
  • The node does not support item publication.
    • +%%
  • The node does not exist.
    • +%%
  • The payload size exceeds a service-defined limit.
    • +%%
  • The item contains more than one payload element or the namespace of the root payload element does not match the configured namespace for the node.
    • +%%
  • The request does not match the node configuration.
    • %%
publish_item(Host, ServerHost, Node, Publisher, "", Payload) -> %% if publisher does not specify an ItemId, the service MUST generate the ItemId @@ -1541,12 +1542,12 @@ publish_item(Host, ServerHost, Node, Publisher, ItemId, Payload) -> %%

The permission to delete an item must be verified by the plugin implementation.

%%

There are several reasons why the item retraction request might fail:

%%
    -%%
  • The publisher does not have sufficient privileges to delete the requested item. -%%
  • The node or item does not exist. -%%
  • The request does not specify a node. -%%
  • The request does not include an element or the element does not specify an ItemId. -%%
  • The node does not support persistent items. -%%
  • The service does not support the deletion of items. +%%
  • The publisher does not have sufficient privileges to delete the requested item.
    • +%%
  • The node or item does not exist.
    • +%%
  • The request does not specify a node.
    • +%%
  • The request does not include an element or the element does not specify an ItemId.
    • +%%
  • The node does not support persistent items.
    • +%%
  • The service does not support the deletion of items.
    • %%
delete_item(Host, Node, Publisher, ItemId) -> delete_item(Host, Node, Publisher, ItemId, false). @@ -1597,10 +1598,10 @@ delete_item(Host, Node, Publisher, ItemId, ForceNotify) -> %% @doc

Delete all items of specified node owned by JID.

%%

There are several reasons why the node purge request might fail:

%%
    -%%
  • The node or service does not support node purging. -%%
  • The requesting entity does not have sufficient privileges to purge the node. -%%
  • The node is not configured to persist items. -%%
  • The specified node does not exist. +%%
  • The node or service does not support node purging.
    • +%%
  • The requesting entity does not have sufficient privileges to purge the node.
    • +%%
  • The node is not configured to persist items.
    • +%%
  • The specified node does not exist.
    • %%
purge_node(Host, Node, Owner) -> Action = fun(#pubsub_node{type = Type, options = Options}) -> @@ -1723,15 +1724,16 @@ get_items(Host, Node) -> %% @spec (Host, Node, LJID) -> any() %% Host = host() %% Node = pubsubNode() -%% LJID = {U,S,""} +%% LJID = {U,S,[]} %% @doc

Resend the last item of a node to the user.

send_last_item(Host, Node, LJID) -> send_items(Host, Node, LJID, last). -%% @spec (Host, Node, LJID) -> any() +%% @spec (Host, Node, LJID, Number) -> any() %% Host = host() %% Node = pubsubNode() %% LJID = {U, S, []} +%% Number = last | integer() %% @doc

Resend the items of a node to the user.

%% @todo use cache-last-item feature send_items(Host, Node, LJID, Number) -> @@ -2020,7 +2022,7 @@ set_subscriptions(Host, Node, From, EntitiesEls) -> end. -% @spec (OwnerUser, OwnerServer, {SubscriberUser, SubscriberServer, _}, AllowedGroups) +%% @spec (OwnerUser, OwnerServer, {SubscriberUser, SubscriberServer, any()}, AllowedGroups) -> {PresenceSubscription, RosterGroup} get_roster_info(OwnerUser, OwnerServer, {SubscriberUser, SubscriberServer, _}, AllowedGroups) -> {Subscription, Groups} = ejabberd_hooks:run_fold( @@ -2094,11 +2096,11 @@ service_jid(Host) -> _ -> {jid, "", Host, "", "", Host, ""} end. -%% @spec (LJID, PresenceDelivery) -> boolean() +%% @spec (LJID, Subscription, PresenceDelivery) -> boolean() %% LJID = jid() %% Subscription = atom() %% PresenceDelivery = boolean() -%% @doc

Check if a notification must be delivered or not +%% @doc

Check if a notification must be delivered or not

is_to_deliver(_, none, _) -> false; is_to_deliver(_, pending, _) -> false; is_to_deliver(_, _, false) -> true; @@ -2113,7 +2115,7 @@ is_to_deliver({User, Server, _}, _, true) -> %% @spec (Els) -> stanza() %% Els = [xmlelement()] -%% @doc

Build pubsub event stanza +%% @doc

Build pubsub event stanza

event_stanza(Els) -> {xmlelement, "message", [], [{xmlelement, "event", [{"xmlns", ?NS_PUBSUB_EVENT}], Els}]}. diff --git a/src/mod_pubsub/node_default.erl b/src/mod_pubsub/node_default.erl index ee10eeb74..e1ca6c410 100644 --- a/src/mod_pubsub/node_default.erl +++ b/src/mod_pubsub/node_default.erl @@ -80,7 +80,7 @@ %% API definition %% ================ -%% @spec (Host) -> any() +%% @spec (Host, ServerHost, Opts) -> any() %% Host = mod_pubsub:host() %% ServerHost = host() %% Opts = list() @@ -110,7 +110,7 @@ init(_Host, _ServerHost, _Opts) -> end, ok. -%% @spec (Host) -> any() +%% @spec (Host, ServerHost) -> any() %% Host = mod_pubsub:host() %% @doc

Called during pubsub modules termination. Any pubsub plugin must %% implement this function. It can return anything.

@@ -173,7 +173,7 @@ features() -> "subscription-notifications" ]. -%% @spec (Host, Node, Owner, Access) -> bool() +%% @spec (Host, ServerHost, Node, ParentNode, Owner, Access) -> bool() %% Host = mod_pubsub:host() %% ServerHost = mod_pubsub:host() %% Node = mod_pubsub:pubsubNode() @@ -239,7 +239,7 @@ delete_node(Host, Removed) -> end, Removed), {result, {default, broadcast, Removed}}. -%% @spec (Host, Node, Sender, Subscriber, AccessModel, SendLast) -> +%% @spec (Host, Node, Sender, Subscriber, AccessModel, SendLast, PresenceSubscription, RosterGroup) -> %% {error, Reason} | {result, Result} %% @doc

Accepts or rejects subcription requests on a PubSub node.

%%

The mechanism works as follow: @@ -557,9 +557,9 @@ set_affiliation(Host, Node, Owner, Affiliation) -> set_state(State#pubsub_state{affiliation = Affiliation}), ok. -%% @spec (Host) -> [{Node,Subscription}] +%% @spec (Host, Ownner) -> [{Node,Subscription}] %% Host = host() -%% JID = mod_pubsub:jid() +%% Owner = mod_pubsub:jid() %% @doc

Return the current subscriptions for the given user

%%

The default module reads subscriptions in the main Mnesia %% pubsub_state table. If a plugin stores its data in the same @@ -627,7 +627,7 @@ get_state(Host, Node, JID) -> _ -> #pubsub_state{stateid=StateId} end. -%% @spec (State) -> ok | {error, ?ERR_INTERNAL_SERVER_ERROR} +%% @spec (State) -> ok | {error, ErrorCode} %% State = mod_pubsub:pubsubStates() %% @doc

Write a state into database.

set_state(State) when is_record(State, pubsub_state) -> @@ -746,7 +746,7 @@ get_item(Host, Node, ItemId, JID, AccessModel, PresenceSubscription, RosterGroup get_item(Host, Node, ItemId) end. -%% @spec (Item) -> ok | {error, ?ERR_INTERNAL_SERVER_ERROR} +%% @spec (Item) -> ok | {error, ErrorCode} %% Item = mod_pubsub:pubsubItems() %% @doc

Write a state into database.

set_item(Item) when is_record(Item, pubsub_item) -> @@ -754,7 +754,7 @@ set_item(Item) when is_record(Item, pubsub_item) -> set_item(_) -> {error, ?ERR_INTERNAL_SERVER_ERROR}. -%% @spec (ItemId) -> ok | {error, Reason::stanzaError()} +%% @spec (Host, Node, ItemId) -> ok | {error, Reason::stanzaError()} %% Host = mod_pubsub:host() %% Node = mod_pubsub:pubsubNode() %% ItemId = string() diff --git a/src/mod_pubsub/nodetree_default.erl b/src/mod_pubsub/nodetree_default.erl index e3bb790a0..aed7a696d 100644 --- a/src/mod_pubsub/nodetree_default.erl +++ b/src/mod_pubsub/nodetree_default.erl @@ -58,7 +58,7 @@ %% API definition %% ================ -%% @spec (Host) -> any() +%% @spec (Host, ServerHost, Opts) -> any() %% Host = mod_pubsub:host() %% ServerHost = host() %% Opts = list() diff --git a/src/mod_pubsub/nodetree_virtual.erl b/src/mod_pubsub/nodetree_virtual.erl index ae2bc0081..ff23664f6 100644 --- a/src/mod_pubsub/nodetree_virtual.erl +++ b/src/mod_pubsub/nodetree_virtual.erl @@ -55,7 +55,7 @@ %% API definition %% ================ -%% @spec (Host) -> any() +%% @spec (Host, ServerHost, Opts) -> any() %% Host = mod_pubsub:host() %% ServerHost = host() %% Opts = list() diff --git a/src/mod_pubsub/pubsub.hrl b/src/mod_pubsub/pubsub.hrl index 3f64b7b23..08123f464 100644 --- a/src/mod_pubsub/pubsub.hrl +++ b/src/mod_pubsub/pubsub.hrl @@ -16,7 +16,7 @@ %%% This software is copyright 2006-2008, ProcessOne. %%% %%% -%%% @copyright 2006-2008 ProcessOne +%%% Copyright 2006-2008 ProcessOne %%% %%% This file contains pubsub types definition. %%% ====================================================================