common_test: Remove EDoc documentation in public modules

1 files changed, 1 insertions, 288 deletions

diff --git a/lib/common_test/src/ct_snmp.erl b/lib/common_test/src/ct_snmp.erl
index 5844909d17..27b74dd04e 100644
--- a/lib/common_test/src/ct_snmp.erl
+++ b/lib/common_test/src/ct_snmp.erl
@@ -1,7 +1,7 @@
 %%
 %% %CopyrightBegin%
 %%
-%% Copyright Ericsson AB 2004-2016. All Rights Reserved.
+%% Copyright Ericsson AB 2004-2018. All Rights Reserved.
 %%
 %% Licensed under the Apache License, Version 2.0 (the "License");
 %% you may not use this file except in compliance with the License.
@@ -18,139 +18,8 @@
 %% %CopyrightEnd%
 %%
 
-%%% @doc Common Test user interface module for the OTP snmp application
-%%%
-%%% <p>The purpose of this module is to make snmp configuration easier for
-%%% the test case writer. Many test cases can use default values for common
-%%% operations and then no snmp configuration files need to be supplied. When
-%%% it is necessary to change particular configuration parameters, a subset
-%%% of the relevant snmp configuration files may be passed to <code>ct_snmp</code>
-%%% by means of Common Test configuration files.
-%%% For more specialized configuration parameters, it is possible to place a 
-%%% "simple snmp configuration file" in the test suite data directory. 
-%%% To simplify the test suite, Common Test keeps track
-%%% of some of the snmp manager information. This way the test suite doesn't
-%%% have to handle as many input parameters as it would if it had to interface the
-%%% OTP snmp manager directly.</p>
-%%% 
-%%% <p> The following snmp manager and agent parameters are configurable: </p>
-%%%
-%%% <pre>
-%%% {snmp,
-%%%        %%% Manager config
-%%%        [{start_manager, boolean()}    % Optional - default is true
-%%%        {users, [{user_name(), [call_back_module(), user_data()]}]}, %% Optional 
-%%%        {usm_users, [{usm_user_name(), [usm_config()]}]},%% Optional - snmp v3 only
-%%%        % managed_agents is optional 
-%%%        {managed_agents,[{agent_name(), [user_name(), agent_ip(), agent_port(), [agent_config()]]}]},   
-%%%        {max_msg_size, integer()},     % Optional - default is 484
-%%%        {mgr_port, integer()},         % Optional - default is 5000
-%%%        {engine _id, string()},        % Optional - default is "mgrEngine"
-%%%
-%%%        %%% Agent config 
-%%%        {start_agent, boolean()},      % Optional - default is false
-%%%        {agent_sysname, string()},     % Optional - default is "ct_test"
-%%%        {agent_manager_ip, manager_ip()}, % Optional - default is localhost
-%%%        {agent_vsns, list()},          % Optional - default is [v2]
-%%%        {agent_trap_udp, integer()},   % Optional - default is 5000
-%%%        {agent_udp, integer()},        % Optional - default is 4000
-%%%        {agent_notify_type, atom()},   % Optional - default is trap
-%%%        {agent_sec_type, sec_type()},  % Optional - default is none
-%%%        {agent_passwd, string()},      % Optional - default is ""
-%%%        {agent_engine_id, string()},   % Optional - default is "agentEngine"
-%%%        {agent_max_msg_size, string()},% Optional - default is 484
-%%%
-%%%        %% The following parameters represents the snmp configuration files
-%%%        %% context.conf, standard.conf, community.conf, vacm.conf,  
-%%%        %% usm.conf, notify.conf, target_addr.conf and target_params.conf.
-%%%        %% Note all values in agent.conf can be altered by the parametes 
-%%%        %% above. All these configuration files have default values set   
-%%%        %% up by the snmp application. These values can be overridden by
-%%%        %% suppling a list of valid configuration values or a file located
-%%%        %% in the test suites data dir that can produce a list 
-%%%        %% of valid configuration values if you apply file:consult/1 to the 
-%%%        %% file. 
-%%%        {agent_contexts, [term()] | {data_dir_file, rel_path()}}, % Optional
-%%%        {agent_community, [term()] | {data_dir_file, rel_path()}},% Optional
-%%%        {agent_sysinfo,  [term()] | {data_dir_file, rel_path()}}, % Optional
-%%%        {agent_vacm, [term()] | {data_dir_file, rel_path()}},     % Optional
-%%%        {agent_usm, [term()] | {data_dir_file, rel_path()}},      % Optional 
-%%%        {agent_notify_def, [term()] | {data_dir_file, rel_path()}},% Optional
-%%%        {agent_target_address_def, [term()] | {data_dir_file, rel_path()}},% Optional
-%%%        {agent_target_param_def, [term()] | {data_dir_file, rel_path()}},% Optional
-%%%       ]}.
-%%% </pre>
-%%%
-%%% <p>The <code>MgrAgentConfName</code> parameter in the functions 
-%%% should be a name you allocate in your test suite using a
-%%% <code>require</code> statement. 
-%%% Example (where <code>MgrAgentConfName = snmp_mgr_agent</code>):</p>
-%%% <pre> suite() -> [{require, snmp_mgr_agent, snmp}].</pre>
-%%% <p>or</p>
-%%% <pre>  ct:require(snmp_mgr_agent, snmp).</pre>
-%%%
-%%% <p> Note that Usm users are needed for snmp v3 configuration and are
-%%% not to be confused with users.</p>
-%%%
-%%% <p> Snmp traps, inform and report messages are handled by the
-%%% user callback module. For more information about this see
-%%% the snmp application. </p> 
-%%% <p> Note: It is recommended to use the .hrl-files created by the 
-%%% Erlang/OTP mib-compiler to define the oids.  
-%%% Example for the getting the erlang node name from the erlNodeTable 
-%%% in the OTP-MIB:</p> 
-%%% <pre>Oid = ?erlNodeEntry ++ [?erlNodeName, 1] </pre>
-%%%
-%%% <p>It is also possible to set values for snmp application configuration 
-%%% parameters, such as <code>config</code>, <code>server</code>, 
-%%% <code>net_if</code>, etc (see the "Configuring the application" chapter in
-%%% the OTP snmp User's Guide for a list of valid parameters and types). This is 
-%%% done by defining a configuration data variable on the following form:</p>
-%%% <pre>
-%%% {snmp_app, [{manager, [snmp_app_manager_params()]},
-%%%             {agent, [snmp_app_agent_params()]}]}.</pre>
-%%% 
-%%% <p>A name for the data needs to be allocated in the suite using 
-%%% <code>require</code> (see example above), and this name passed as 
-%%% the <code>SnmpAppConfName</code> argument to <code>start/3</code>.
-%%% <code>ct_snmp</code> specifies default values for some snmp application
-%%% configuration parameters (such as <code>{verbosity,trace}</code> for the
-%%% <code>config</code> parameter). This set of defaults will be
-%%% merged with the parameters specified by the user, and user values
-%%% override <code>ct_snmp</code> defaults.</p>
-
 -module(ct_snmp).
 
-%%% Common Types
-%%% @type agent_ip() = ip()
-%%% @type manager_ip() = ip()
-%%% @type agent_name() = atom()
-%%% @type ip() = string() | {integer(), integer(), 
-%%% integer(), integer()}
-%%% @type agent_port() = integer()
-%%% @type agent_config() = {Item, Value} 
-%%% @type user_name() = atom() 
-%%% @type usm_user_name() = string() 
-%%% @type usm_config() = {Item, Value}
-%%% @type call_back_module() = atom()
-%%% @type user_data() = term() 
-%%% @type oids() = [oid()]
-%%% @type oid() = [byte()]
-%%% @type snmpreply() = {error_status(), error_index(), varbinds()} 
-%%% @type error_status() = noError | atom() 
-%%% @type error_index() = integer() 
-%%% @type varbinds() = [varbind()] 
-%%% @type varbind() =  term() 
-%%% @type value_type() = o ('OBJECT IDENTIFIER') | i ('INTEGER') | 
-%%% u ('Unsigned32') | g ('Unsigned32') | s ('OCTET STRING') 
-%%% @type varsandvals() = [var_and_val()]
-%%% @type var_and_val() = {oid(), value_type(), value()}
-%%% @type sec_type() = none | minimum | semi
-%%% @type rel_path() = string() 
-%%% @type snmp_app_manager_params() = term()
-%%% @type snmp_app_agent_params() = term()
-
-
 -include("snmp_types.hrl").
 -include("inet.hrl").
 -include("ct.hrl").
@@ -181,31 +50,9 @@
 %%%  API
 %%%=========================================================================
 
-%%%-----------------------------------------------------------------
-%%% @spec start(Config, MgrAgentConfName) -> ok
-%%% @equiv start(Config, MgrAgentConfName, undefined)
 start(Config, MgrAgentConfName) ->
     start(Config, MgrAgentConfName, undefined).
 
-%%% @spec start(Config, MgrAgentConfName, SnmpAppConfName) -> ok
-%%%      Config = [{Key, Value}] 
-%%%      Key = atom()
-%%%      Value = term()
-%%%      MgrAgentConfName = atom()
-%%%      SnmpConfName = atom()
-%%%
-%%% @doc Starts an snmp manager and/or agent. In the manager case,
-%%% registrations of users and agents as specified by the configuration 
-%%% <code>MgrAgentConfName</code> will be performed. When using snmp
-%%% v3 also so called usm users will be registered. Note that users,
-%%% usm_users and managed agents may also be registered at a later time
-%%% using ct_snmp:register_users/2, ct_snmp:register_agents/2, and
-%%% ct_snmp:register_usm_users/2. The agent started will be
-%%% called <code>snmp_master_agent</code>. Use ct_snmp:load_mibs/1 to load 
-%%% mibs into the agent. With <code>SnmpAppConfName</code> it's possible 
-%%% to configure the snmp application with parameters such as <code>config</code>,
-%%% <code>mibs</code>, <code>net_if</code>, etc. The values will be merged
-%%% with (and possibly override) default values set by <code>ct_snmp</code>.
 start(Config, MgrAgentConfName, SnmpAppConfName) ->
     StartManager= ct:get_config({MgrAgentConfName, start_manager}, true),
     StartAgent = ct:get_config({MgrAgentConfName, start_agent}, false),
@@ -233,12 +80,6 @@ start_application(App) ->
             Else
     end.
  
-%%% @spec stop(Config) -> ok
-%%%      Config = [{Key, Value}]
-%%%      Key = atom()
-%%%      Value = term()
-%%%
-%%% @doc Stops the snmp manager and/or agent removes all files created.
 stop(Config) ->
     PrivDir = ?config(priv_dir, Config),
     ok = application:stop(snmp),
@@ -251,41 +92,16 @@ stop(Config) ->
     catch del_dir(DbDir).
     
     
-%%% @spec get_values(Agent, Oids, MgrAgentConfName) -> SnmpReply
-%%%
-%%%	 Agent = agent_name()
-%%%      Oids = oids()
-%%%      MgrAgentConfName = atom()
-%%%      SnmpReply = snmpreply()  
-%%%
-%%% @doc Issues a synchronous snmp get request. 
 get_values(Agent, Oids, MgrAgentConfName) ->
     [Uid | _] = agent_conf(Agent, MgrAgentConfName),
     {ok, SnmpReply, _} = snmpm:sync_get2(Uid, target_name(Agent), Oids),
     SnmpReply.
 
-%%% @spec get_next_values(Agent, Oids, MgrAgentConfName) -> SnmpReply 
-%%%
-%%%	 Agent = agent_name()
-%%%      Oids = oids()
-%%%      MgrAgentConfName = atom()
-%%%      SnmpReply = snmpreply()  
-%%%
-%%% @doc Issues a synchronous snmp get next request. 
 get_next_values(Agent, Oids, MgrAgentConfName) ->
     [Uid | _] = agent_conf(Agent, MgrAgentConfName),
     {ok, SnmpReply, _} = snmpm:sync_get_next2(Uid, target_name(Agent), Oids),
     SnmpReply.
 
-%%% @spec set_values(Agent, VarsAndVals, MgrAgentConfName, Config) -> SnmpReply
-%%%
-%%%	 Agent = agent_name()
-%%%      Oids = oids()
-%%%      MgrAgentConfName = atom()
-%%%      Config = [{Key, Value}] 
-%%%      SnmpReply = snmpreply()  
-%%%
-%%% @doc Issues a synchronous snmp set request. 
 set_values(Agent, VarsAndVals, MgrAgentConfName, Config) ->
     PrivDir = ?config(priv_dir, Config),
     [Uid | _] = agent_conf(Agent, MgrAgentConfName),
@@ -301,19 +117,6 @@ set_values(Agent, VarsAndVals, MgrAgentConfName, Config) ->
     end,
     SnmpSetReply.
 
-%%% @spec set_info(Config) -> [{Agent, OldVarsAndVals, NewVarsAndVals}] 
-%%%
-%%%      Config = [{Key, Value}] 
-%%%	 Agent = agent_name()
-%%%      OldVarsAndVals = varsandvals()
-%%%      NewVarsAndVals = varsandvals()
-%%%
-%%% @doc Returns a list of all successful set requests performed in
-%%% the test case in reverse order. The list contains the involved
-%%% user and agent, the value prior to the set and the new value. This
-%%% is intended to facilitate the clean up in the end_per_testcase
-%%% function i.e. the undoing of the set requests and its possible
-%%% side-effects.
 set_info(Config) ->
     PrivDir = ?config(priv_dir, Config),
     SetLogFile = filename:join(PrivDir, ?CT_SNMP_LOG_FILE),
@@ -325,18 +128,6 @@ set_info(Config) ->
 	    []
     end.
 
-%%% @spec register_users(MgrAgentConfName, Users) -> ok | {error, Reason}
-%%%
-%%%      MgrAgentConfName = atom()
-%%%      Users =  [user()]
-%%%      Reason = term()    
-%%%
-%%% @doc Register the manager entity (=user) responsible for specific agent(s).
-%%% Corresponds to making an entry in users.conf.
-%%%
-%%% <p>This function will try to register the given users, without
-%%% checking if any of them already exist. In order to change an
-%%% already registered user, the user must first be unregistered.</p>
 register_users(MgrAgentConfName, Users) ->
     case setup_users(Users) of
 	ok ->
@@ -350,19 +141,6 @@ register_users(MgrAgentConfName, Users) ->
 	    Error
     end.
 
-%%% @spec register_agents(MgrAgentConfName, ManagedAgents) -> ok | {error, Reason}
-%%%
-%%%      MgrAgentConfName = atom()
-%%%      ManagedAgents = [agent()]
-%%%      Reason = term()    
-%%%
-%%% @doc Explicitly instruct the manager to handle this agent.
-%%% Corresponds to making an entry in agents.conf 
-%%%
-%%% <p>This function will try to register the given managed agents,
-%%% without checking if any of them already exist. In order to change
-%%% an already registered managed agent, the agent must first be
-%%% unregistered.</p>
 register_agents(MgrAgentConfName, ManagedAgents) ->
     case setup_managed_agents(MgrAgentConfName,ManagedAgents) of
 	ok ->
@@ -377,18 +155,6 @@ register_agents(MgrAgentConfName, ManagedAgents) ->
 	    Error
     end.
 
-%%% @spec register_usm_users(MgrAgentConfName, UsmUsers) ->  ok | {error, Reason}
-%%%
-%%%      MgrAgentConfName = atom()
-%%%      UsmUsers = [usm_user()]
-%%%      Reason = term()    
-%%%
-%%% @doc Explicitly instruct the manager to handle this USM user.
-%%% Corresponds to making an entry in usm.conf 
-%%%
-%%% <p>This function will try to register the given users, without
-%%% checking if any of them already exist. In order to change an
-%%% already registered user, the user must first be unregistered.</p>
 register_usm_users(MgrAgentConfName, UsmUsers) ->
     EngineID = ct:get_config({MgrAgentConfName, engine_id}, ?ENGINE_ID),
     case setup_usm_users(UsmUsers, EngineID) of
@@ -403,23 +169,10 @@ register_usm_users(MgrAgentConfName, UsmUsers) ->
 	    Error
     end.
 
-%%% @spec unregister_users(MgrAgentConfName) ->  ok
-%%%
-%%%      MgrAgentConfName = atom()
-%%%      Reason = term()
-%%%
-%%% @doc Unregister all users.
 unregister_users(MgrAgentConfName) ->
     Users = [Id || {Id,_} <- ct:get_config({MgrAgentConfName, users},[])],
     unregister_users(MgrAgentConfName,Users).
 
-%%% @spec unregister_users(MgrAgentConfName,Users) ->  ok
-%%%
-%%%      MgrAgentConfName = atom()
-%%%      Users = [user_name()]
-%%%      Reason = term()
-%%%
-%%% @doc Unregister the given users.
 unregister_users(MgrAgentConfName,Users) ->
     takedown_users(Users),
     SnmpVals = ct:get_config(MgrAgentConfName),
@@ -432,25 +185,12 @@ unregister_users(MgrAgentConfName,Users) ->
     ct_config:update_config(MgrAgentConfName, NewSnmpVals),
     ok.
 
-%%% @spec unregister_agents(MgrAgentConfName) ->  ok
-%%%
-%%%      MgrAgentConfName = atom()
-%%%      Reason = term()
-%%%
-%%% @doc  Unregister all managed agents.
 unregister_agents(MgrAgentConfName) ->    
     ManagedAgents =  [AgentName ||
 			 {AgentName, _} <-
 			     ct:get_config({MgrAgentConfName,managed_agents},[])],
     unregister_agents(MgrAgentConfName,ManagedAgents).
 
-%%% @spec unregister_agents(MgrAgentConfName,ManagedAgents) ->  ok
-%%%
-%%%      MgrAgentConfName = atom()
-%%%      ManagedAgents = [agent_name()]
-%%%      Reason = term()
-%%%
-%%% @doc  Unregister the given managed agents.
 unregister_agents(MgrAgentConfName,ManagedAgents) ->
     takedown_managed_agents(MgrAgentConfName, ManagedAgents),
     SnmpVals = ct:get_config(MgrAgentConfName),
@@ -464,23 +204,10 @@ unregister_agents(MgrAgentConfName,ManagedAgents) ->
     ct_config:update_config(MgrAgentConfName, NewSnmpVals),
     ok.
 
-%%% @spec unregister_usm_users(MgrAgentConfName) ->  ok
-%%%
-%%%      MgrAgentConfName = atom()
-%%%      Reason = term()
-%%%
-%%% @doc Unregister all usm users.
 unregister_usm_users(MgrAgentConfName) ->
     UsmUsers = [Id || {Id,_} <- ct:get_config({MgrAgentConfName, usm_users},[])],
     unregister_usm_users(MgrAgentConfName,UsmUsers).
 
-%%% @spec unregister_usm_users(MgrAgentConfName,UsmUsers) ->  ok
-%%%
-%%%      MgrAgentConfName = atom()
-%%%      UsmUsers = [usm_user_name()]
-%%%      Reason = term()
-%%%
-%%% @doc Unregister the given usm users.
 unregister_usm_users(MgrAgentConfName,UsmUsers) ->
     EngineID = ct:get_config({MgrAgentConfName, engine_id}, ?ENGINE_ID),
     takedown_usm_users(UsmUsers,EngineID),
@@ -495,23 +222,9 @@ unregister_usm_users(MgrAgentConfName,UsmUsers) ->
     ct_config:update_config(MgrAgentConfName, NewSnmpVals),
     ok.
 
-%%% @spec load_mibs(Mibs) -> ok | {error, Reason}
-%%%
-%%%      Mibs = [MibName]
-%%%      MibName = string()
-%%%      Reason = term()
-%%%
-%%% @doc Load the mibs into the agent 'snmp_master_agent'.
 load_mibs(Mibs) ->       
     snmpa:load_mibs(snmp_master_agent, Mibs).
  
-%%% @spec unload_mibs(Mibs) -> ok | {error, Reason}
-%%%
-%%%      Mibs = [MibName]
-%%%      MibName = string()
-%%%      Reason = term()
-%%%
-%%% @doc Unload the mibs from the agent 'snmp_master_agent'.
 unload_mibs(Mibs) ->
     snmpa:unload_mibs(snmp_master_agent, Mibs).