From: Guilherme Maciel Ferreira Date: Wed, 4 May 2011 16:26:27 +0000 (+0200) Subject: Added doxygen comments in the most important places. X-Git-Tag: v1.0~21 X-Git-Url: http://developer.intra2net.com/git/?a=commitdiff_plain;h=5a3f61892485a075778da784298944d516423906;p=pingcheck Added doxygen comments in the most important places. --- diff --git a/TODO b/TODO index 6d586e7..5cc25de 100644 --- a/TODO +++ b/TODO @@ -27,8 +27,6 @@ TODO Guilherme: - fix config parser: -- Documentation of the functions (doxygen) - - The interval between each ping to the same host is 1 second later than in the configuration file. For example, a ping configured to be performed each 5 seconds takes 6. diff --git a/src/config/configurationreader.cpp b/src/config/configurationreader.cpp index 5ec85c8..28f9e62 100644 --- a/src/config/configurationreader.cpp +++ b/src/config/configurationreader.cpp @@ -63,6 +63,14 @@ ConfigurationReader::~ConfigurationReader() { } +/** + * @brief Parses the command line and configuration file. + * + * @param argc the number of arguments in command line. + * @param argv a vector containing the command line elements. + * + * @return true if the parsing was successful, otherwise returns false. + */ bool ConfigurationReader::parse( const int argc, char *argv[] @@ -98,11 +106,17 @@ bool ConfigurationReader::parse( } } +/** + * @return the object containing the configuration data parsed by this object. + */ Configuration ConfigurationReader::get_configuration() const { return Config; } +/** + * @return which options must abort the application. Like the --version. + */ bool ConfigurationReader::halt_on_generic_options( const variables_map &vm ) const { bool is_help = ( vm.count( HelpCmdStr ) > 0 ); @@ -317,6 +331,14 @@ bool ConfigurationReader::parse_configuration_options( const variables_map &vm ) return true; } +/** + * @brief Reads and parses the command line, storing the parsed tokens in the + * variables_map. + * + * @param argc the number of arguments in command line. + * @param argv a vector containing the command line elements. + * @param vm the variables_map object to store configuration tokens. + */ bool ConfigurationReader::process_command_line( const int argc, char *argv[], @@ -351,6 +373,12 @@ bool ConfigurationReader::process_command_line( } } +/** + * @brief Reads and parses the configuration file. The file name is retrieved + * from the variables_map object. + * + * @param vm the variables_map object to store configuration tokens. + */ bool ConfigurationReader::process_configuration_file( variables_map &vm ) { string config_file_name = ""; @@ -365,6 +393,12 @@ bool ConfigurationReader::process_configuration_file( variables_map &vm ) return process_configuration_file( config_file_name, vm ); } +/** + * @brief Reads and parses the configuration file. + * + * @param config_file_name the configuration file name to be parsed. + * @param vm the variables_map object to store configuration tokens. + */ bool ConfigurationReader::process_configuration_file( const string &config_file_name, variables_map &vm diff --git a/src/config/configurationreader.h b/src/config/configurationreader.h index 084ee46..b522bbd 100644 --- a/src/config/configurationreader.h +++ b/src/config/configurationreader.h @@ -11,6 +11,9 @@ // ConfigurationReader //----------------------------------------------------------------------------- +/** + * @brief This class represents the configuration parsing process. + */ class ConfigurationReader { public: diff --git a/src/config/host.cpp b/src/config/host.cpp index 82b82a4..9f85e95 100644 --- a/src/config/host.cpp +++ b/src/config/host.cpp @@ -13,8 +13,7 @@ using namespace std; Host::Host( string address ) : Address( address ), Port( 0 ), - IntervalInSec( 0 ), - Options() + IntervalInSec( 0 ) { } @@ -22,11 +21,17 @@ Host::~Host() { } +/** + * @return a string representing the host address. + */ string Host::get_address() const { return Address; } +/** + * @param address a string representing the host address. + */ void Host::set_address( const string &address ) { BOOST_ASSERT( !address.empty() ); @@ -34,11 +39,17 @@ void Host::set_address( const string &address ) this->Address = address; } +/** + * @return the destination port number to ping the host. + */ uint16_t Host::get_port() const { return Port; } +/** + * @param port the destination port number to ping the host. + */ void Host::set_port( const uint16_t port ) { BOOST_ASSERT( ( 0 < port ) && ( port < numeric_limits::max() ) ); @@ -46,26 +57,20 @@ void Host::set_port( const uint16_t port ) this->Port = port; } +/** + * @return the interval between each ping to the host. + */ int Host::get_interval_in_sec() const { return IntervalInSec; } +/** + * @param interval_in_sec the interval between each ping to the host. + */ void Host::set_interval_in_sec( const int interval_in_sec ) { BOOST_ASSERT( ( 0 < interval_in_sec ) && ( interval_in_sec < numeric_limits::max() ) ); this->IntervalInSec = interval_in_sec; } - -vector Host::get_options() const -{ - return Options; -} - -void Host::set_options( const vector &options ) -{ - BOOST_ASSERT( 0 < options.size() ); - - this->Options = options; -} diff --git a/src/config/host.h b/src/config/host.h index 02d292f..e0e5247 100644 --- a/src/config/host.h +++ b/src/config/host.h @@ -27,9 +27,6 @@ public: int get_interval_in_sec() const; void set_interval_in_sec( const int interval_in_sec ); - std::vector get_options() const; - void set_options( const std::vector &options ); - private: /// the address of the host std::string Address; @@ -37,8 +34,6 @@ private: uint16_t Port; /// the interval between each ping to the host int IntervalInSec; - /// options - std::vector Options; }; diff --git a/src/dns/dnsresolver.cpp b/src/dns/dnsresolver.cpp index a649c13..f1caf47 100644 --- a/src/dns/dnsresolver.cpp +++ b/src/dns/dnsresolver.cpp @@ -71,7 +71,7 @@ bool DnsResolver::handle_ip_address() } /** - * Resolve the IPs from this DNS and build a list of these IPs. + * @brief Resolve the IPs from this DNS and build a list of these IPs. * * @return true if the host address could be resolved, or false otherwise. */ diff --git a/src/dns/timetolive.cpp b/src/dns/timetolive.cpp index 21e02c1..4e884c2 100644 --- a/src/dns/timetolive.cpp +++ b/src/dns/timetolive.cpp @@ -20,11 +20,17 @@ TimeToLive::~TimeToLive() { } +/** + * @return the original time-to-live value, as specified by the set method. + */ int TimeToLive::get_value() const { return Ttl; } +/** + * @param ttl the time-to-live value. + */ void TimeToLive::set_value( const int ttl ) { BOOST_ASSERT( 0 < ttl ); @@ -33,6 +39,9 @@ void TimeToLive::set_value( const int ttl ) TtlSetTime = microsec_clock::universal_time(); } +/** + * @return the value of the time-to-live updated since the last set was called. + */ int TimeToLive::get_updated_value() const { ptime now = microsec_clock::universal_time(); diff --git a/src/icmp/icmpmessagepayload.cpp b/src/icmp/icmpmessagepayload.cpp index 36032a0..ce497c1 100644 --- a/src/icmp/icmpmessagepayload.cpp +++ b/src/icmp/icmpmessagepayload.cpp @@ -11,6 +11,9 @@ using boost::scoped_array; // IcmpMessagePayload //----------------------------------------------------------------------------- +/** + * @param payload_size_in_bytes the size of the payload (ie the internal buffer) + */ IcmpMessagePayload::IcmpMessagePayload( const std::size_t &payload_size_in_bytes ) : @@ -27,6 +30,10 @@ IcmpMessagePayload::~IcmpMessagePayload() // Payload automatically delete by smart pointer scope end } +/** + * @brief The element access operator to provide access syntax like regular + * arrays. + */ const uint8_t& IcmpMessagePayload::operator[]( size_t offset ) const { BOOST_ASSERT( offset < PayloadSizeInBytes ); @@ -34,6 +41,10 @@ const uint8_t& IcmpMessagePayload::operator[]( size_t offset ) const return Payload[ offset ]; } +/** + * @brief The element access operator to provide access syntax like regular + * arrays. + */ uint8_t& IcmpMessagePayload::operator[]( size_t offset ) { BOOST_ASSERT( offset < PayloadSizeInBytes ); @@ -41,6 +52,15 @@ uint8_t& IcmpMessagePayload::operator[]( size_t offset ) return Payload[ offset ]; } +/** + * @brief Retrieve 16 bits from the payload buffer. + * + * @param left_byte the index of the left byte + * @param right_byte the index of the right byte + * + * @return a concatenation of the byte indexed by left_byte with the byte + * indexed by right_byte + */ uint16_t IcmpMessagePayload::decode( const int left_byte, const int right_byte @@ -53,6 +73,15 @@ uint16_t IcmpMessagePayload::decode( return static_cast ( value ); } +/** + * @brief Store 16 bits in the payload buffer. + * + * @param left_byte the index of the left byte + * @param right_byte the index of the right byte + * + * @param value a 16 bits data be saved in the bytes indexed by left_byte and + * right_byte. + */ void IcmpMessagePayload::encode( const int left_byte, const int right_byte, @@ -63,6 +92,9 @@ void IcmpMessagePayload::encode( Payload[ right_byte ] = static_cast ( value & 0xFF ); } +/** + * @brief Read all the data from the payload and stores in the istream. + */ istream& IcmpMessagePayload::read( istream &is ) { char *data_array = reinterpret_cast ( Payload.get() ); @@ -73,6 +105,9 @@ istream& IcmpMessagePayload::read( istream &is ) return is; } +/** + * @brief Writes all the data present in the ostream to the payload buffer. + */ ostream& IcmpMessagePayload::write( ostream &os ) const { const char *data_array = reinterpret_cast ( Payload.get() ); diff --git a/src/icmp/icmpmessagepayload.h b/src/icmp/icmpmessagepayload.h index 3e77fa4..386d7d6 100644 --- a/src/icmp/icmpmessagepayload.h +++ b/src/icmp/icmpmessagepayload.h @@ -18,6 +18,11 @@ // IcmpMessagePayload //----------------------------------------------------------------------------- +/** + * @brief This class represents the contents of the network messages. It + * provides means for encode and decode, and also can be treated like an + * ordinary array. + */ class IcmpMessagePayload { public: diff --git a/src/link/linkstatusanalyzer.cpp b/src/link/linkstatusanalyzer.cpp index cf7a637..c6e036d 100644 --- a/src/link/linkstatusanalyzer.cpp +++ b/src/link/linkstatusanalyzer.cpp @@ -19,6 +19,18 @@ typedef lock_guard mutex_lock_guard; // LinkStatusAnalyzer //----------------------------------------------------------------------------- +/** + * @brief Creates a link status object. + * + * @param hosts_down_limit the maximum amount of different hosts that can be + * down before the system take any action. + * @param link_up_interval_in_min the amount of time required to the link to + * stay up before notify. + * @param link_down_interval_in_min the amount of time required to the link to + * stay down before notify. + * @param status_notifier_cmd the command used to notify about link status + * changes. + */ LinkStatusAnalyzer::LinkStatusAnalyzer( const int hosts_down_limit, const int link_up_interval_in_min, @@ -44,6 +56,14 @@ LinkStatusAnalyzer::~LinkStatusAnalyzer() { } +/** + * @brief Notify the system that a given host is up. The object takes an + * appropriated action to deal with that. + * Note: this object does not resolves IPs, thus you have to send the same host + * address in order to the object to consider the same host. + * + * @param host_address the DNS/IP address of the host that is up. + */ void LinkStatusAnalyzer::notify_host_up( const string &host_address ) { BOOST_ASSERT( !host_address.empty() ); @@ -63,6 +83,14 @@ void LinkStatusAnalyzer::notify_host_up( const string &host_address ) BOOST_ASSERT( HostsDownList.count( host_address ) == 0 ); } +/** + * @brief Notify the system that a given host is down. The object takes an + * appropriated action to deal with that. + * Note: this object does not resolves IPs, thus you have to send the same host + * address in order to the object to consider the same host. + * + * @param host_address the DNS/IP address of the host that is down. + */ void LinkStatusAnalyzer::notify_host_down( const string &host_address ) { BOOST_ASSERT( !host_address.empty() ); diff --git a/src/link/statusnotifiercommand.cpp b/src/link/statusnotifiercommand.cpp index f652cd0..c062946 100644 --- a/src/link/statusnotifiercommand.cpp +++ b/src/link/statusnotifiercommand.cpp @@ -31,6 +31,15 @@ StatusNotifierCommand::~StatusNotifierCommand() { } +/** + * @brief Replaces the token by the value in the notifier command. + * + * @param token actual string in the command. + * @param value string to replace the token. + * + * @return true if the token was find and replaced, or false if it was not + * found, neither replaced. + */ bool StatusNotifierCommand::set_token_value( const string &token, const string &value @@ -54,6 +63,11 @@ bool StatusNotifierCommand::set_token_value( return true; } +/** + * @brief Tries to execute the notify command. + * + * @return true if the command could be executed. false otherwise. + */ bool StatusNotifierCommand::execute() const { // Check if users wants notification at all