From: Tomek Mrugalski Date: Mon, 19 Mar 2012 13:54:18 +0000 (+0100) Subject: [1531] Several developer documentation updates: X-Git-Tag: trac2351_base~226^2~158^2~11^2~1 X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=21c1954e0e26413c1110f68d2b7c730ae79c3d44;p=thirdparty%2Fkea.git [1531] Several developer documentation updates: - Added make devel target in doc directory. - Doxygen warnings/errors are now part of the Developer's guide itself. - renamed mainpage.dox file - Added extra information to main page - Extended libdhcp++ descriptions - Added doc/.gitignore to ignore doc/html (potentially 1000s of files) --- diff --git a/doc/.gitignore b/doc/.gitignore new file mode 100644 index 0000000000..1936cc1d44 --- /dev/null +++ b/doc/.gitignore @@ -0,0 +1 @@ +html diff --git a/doc/Doxyfile b/doc/Doxyfile index 3b9e9f239e..d7706d2d01 100644 --- a/doc/Doxyfile +++ b/doc/Doxyfile @@ -652,7 +652,7 @@ EXAMPLE_RECURSIVE = NO # directories that contain image that are included in the documentation (see # the \image command). -IMAGE_PATH = +IMAGE_PATH = ../doc/images # The INPUT_FILTER tag can be used to specify a program that doxygen should # invoke to filter for each input file. Doxygen will invoke the filter program diff --git a/doc/Makefile.am b/doc/Makefile.am index c18d198fec..833a56c740 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -5,9 +5,9 @@ EXTRA_DIST = version.ent.in devel: mkdir -p html doxygen Doxyfile > html/doxygen.log 2> html/doxygen-error.log - echo "`wc -l html/doxygen-error.log` errors detected." + echo "`wc -l html/doxygen-error.log` warnings/errors detected." -# That's a bit of a hack, but we are makeing sure that devel target +# That's a bit of a hack, but we are making sure that devel target # is always valid. The alternative is to make devel depend on all # *.cc *.h files in the whole tree. .PHONY: devel diff --git a/doc/devel/00-mainpage.dox b/doc/devel/00-mainpage.dox deleted file mode 100644 index 1ebda2baa7..0000000000 --- a/doc/devel/00-mainpage.dox +++ /dev/null @@ -1,28 +0,0 @@ -/** - * - * @mainpage BIND10 Developer's Guide - * - * Welcome to BIND10 Developer's Guide. This documentation is addressed - * at existing and prospecting developers and programmers, who would like - * to gain insight into internal workings of BIND 10. - * - * If you are a user or system administrator, rather than software engineer, - * you should read BIND10 Guide instead. - * - * @section DNS - * - @subpage DataScrubbing - * @section DHCP - - * - @subpage dhcpv4 - * - @subpage dhcpv6 - * - @subpage libdhcp - * - * @section Miscellaneous topics - * - @subpage LoggingApi - * - @subpage LoggingApiOverview - * - @subpage LoggingApiLoggerNames - * - @subpage LoggingApiLoggingMessages - * - @subpage SocketSessionUtility - * - * Documentation warnings and errors - */ \ No newline at end of file diff --git a/doc/devel/02-dhcp.dox b/doc/devel/02-dhcp.dox index d0a2a6b7f6..7ebd9b203a 100644 --- a/doc/devel/02-dhcp.dox +++ b/doc/devel/02-dhcp.dox @@ -1,32 +1,117 @@ /** - * @page dhcpv4 DHCPv4 Component + * @page dhcpv4 DHCPv4 Server Component * - * BIND10 offers DHCPv4 server implementation. It is implemented as b10-dhcp4 component. - * It's primary code is located in isc::dhcp::Dhcpv4Srv class. It uses \ref libdhcp extensively, - * especially isc::dhcp::Pkt4, isc::dhcp::Option and isc::dhcp::IfaceMgr classes. + * BIND10 offers DHCPv4 server implementation. It is implemented as + * b10-dhcp4 component. Its primary code is located in + * isc::dhcp::Dhcpv4Srv class. It uses \ref libdhcp extensively, + * especially isc::dhcp::Pkt4, isc::dhcp::Option and + * isc::dhcp::IfaceMgr classes. Currently this code offers skeleton + * functionality, i.e. it is able to receive and process incoming + * requests and trasmit responses. However, it does not have database + * management, so it returns only one, hardcoded lease to whoever asks + * for it. * - * @todo Describe DHCPv4 component properly. - * - * @page dhcpv6 DHCPv6 Component + * DHCPv4 server component does not support direct traffic (relayed + * only), as support for transmission to hosts without IPv4 address + * assigned is not implemented in IfaceMgr yet. + * + * DHCPv4 server component does not listen to BIND10 message queue. + * + * DHCPv4 server component does not use BIND10 logging yet. + * + * DHCPv4 server component is not integrated with boss yet. + * + * @page dhcpv6 DHCPv6 Server Component + * + * BIND10 offers DHCPv6 server implementation. It is implemented as + * b10-dhcp6 component. Its primary code is located in + * isc::dhcp::Dhcpv6Srv class. It uses \ref libdhcp extensively, + * especially lib::dhcp::Pkt6, isc::dhcp::Option and + * isc::dhcp::IfaceMgr classes. Currently this code offers skeleton + * functionality, i.e. it is able to receive and process incoming + * requests and trasmit responses. However, it does not have database + * management, so it returns only one, hardcoded lease to whoever asks + * for it. + * + * DHCPv6 server component does not support relayed traffic yet, as + * support for relay decapsulation is not implemented yet. + * + * DHCPv6 server component does not listen to BIND10 message queue. + * + * DHCPv6 server component does not use BIND10 logging yet. + * + * DHCPv6 server component is not integrated with boss yet. * - * @todo DHCPv6 component will be described here. - * * @page libdhcp libdhcp++ library * * @section libdhcpIntro Libdhcp++ Introduction * - * libdhcp++ is an all-purpose DHCP-manipulation library, written in C++. It offers packet - * parsing and assembly, DHCPv4 and DHCPv6 options parsing and assembly, interface detection - * (currently on Linux systems only) and socket operations. Following classes are implemented: + * libdhcp++ is an all-purpose DHCP-manipulation library, written in + * C++. It offers packet parsing and assembly, DHCPv4 and DHCPv6 + * options parsing and ssembly, interface detection (currently on + * Linux systems only) and socket operations. Following classes are + * implemented: * * - isc::dhcp::Pkt4 - represents DHCPv4 packet. * - isc::dhcp::Pkt6 - represents DHCPv6 packet. * + * There are two pointer types defined: Pkt4Ptr and Pkt6Ptr. They are + * smart pointer and are using boost::shared_ptr. There are not const + * versions defined, as we assume that hooks can modify any aspect of + * the packet at almost any stage of processing. + * + * Both packets use collection of Option objects to represent DHCPv4 + * and DHCPv6 options. The base class -- Option -- can be used to + * represent generic option that contains collection of + * bytes. Depending on if the option is instantiated as v4 or v6 + * option, it will adjust its header (DHCPv4 options use 1 octet for + * type and 1 octet for length, while DHCPv6 options use 2 bytes for + * each). + * + * There are many specialized classes that are intended to handle options with + * specific content: + * - isc::dhcp::Option4AddrLst -- DHCPv4 option, contains one or more IPv4 addresses; + * - isc::dhcp::Option6AddrLst -- DHCPv6 option, contains one or more IPv6 addresses; + * - isc::dhcp::Option6IAAddr -- DHCPv6 option, represents IAADDR_OPTION (an option that + * contains IPv6 address with extra parameters); + * - isc::dhcp::Option6IA -- DHCPv6 option used to store IA_NA and its suboptions. + * + * All options can store sub-options (i.e. options that are stored within option + * rather than in a message directly). This functionality is commonly used in + * DHCPv6, but is rarely used in DHCPv4. isc::dhcp::Option::addOption(), + * isc::dhcp::Option::delOption(), isc::dhcp::Option::getOption() can be used + * for that purpose. + * * @section lidhcpIfaceMgr Interface Manager * - * Interface Manager (or IfaceMgr) is an abstraction layer about low-level network operations. - * In particlar, it provides information about existing network interfaces See isc::dhcp::IfaceMgr::Iface - * class and isc::dhcp::IfaceMgr::detectIfaces() and isc::dhcp::IfaceMgr::getIface(). - * Another useful methods are dedicated to transmission (isc::dhcp::IfaceMgr::send(), 2 overloads) - * and reception (isc::dhcp::IfaceMgr::receive4() and isc::dhcp::IfaceMgr::receive6()). + * Interface Manager (or IfaceMgr) is an abstraction layer about low-level + * network operations. In particlar, it provides information about existing + * network interfaces See isc::dhcp::IfaceMgr::Iface class and + * isc::dhcp::IfaceMgr::detectIfaces() and isc::dhcp::IfaceMgr::getIface(). + * + * Currently there is interface detection is implemented in Linux only. There + * are plans to implement such support for other OSes, but they remain low + * priority for now. + * + * Generic parts of the code are isc::dhcp::IfaceMgr class in + * src/lib/dhcp/iface_mgr.cc file. OS-specific code is located in separate + * files, e.g. iface_mgr_linux.cc. Such separation should be maintained when + * additional code will be developed. + * + * For systems that interface detection is not supported on, there is a stub + * mechanism implemented. It assumes that interface name is read from a text + * file. This is a temporary solution and will be removed as soon as proper + * interface detection is implemented. It is not going to be developed further. + * To use this feature, store interfaces.txt file. It uses a simple syntax. + * Each line represents an interface name, followed by IPv4 or IPv6 address + * that follows it. This is usually link-local IPv6 address that the server + * should bind to. In theory this mechanism also supports IPv4, but it was + * never tested. The code currently supports only a single interface defined + * that way. + * + * Another useful methods are dedicated to transmission + * (isc::dhcp::IfaceMgr::send(), 2 overloads) and reception + * (isc::dhcp::IfaceMgr::receive4() and isc::dhcp::IfaceMgr::receive6()). + * Note that receive4() and receive6() methods may return NULL, e.g. + * when timeout is reached or if dhcp daemon receives a signal. */ \ No newline at end of file diff --git a/doc/devel/mainpage.dox b/doc/devel/mainpage.dox new file mode 100644 index 0000000000..fd14a44683 --- /dev/null +++ b/doc/devel/mainpage.dox @@ -0,0 +1,35 @@ +/** + * + * @mainpage BIND10 Developer's Guide + * + * Welcome to BIND10 Developer's Guide. This documentation is addressed + * at existing and prospecting developers and programmers, who would like + * to gain insight into internal workings of BIND 10. It could also be useful + * for existing and prospective contributors. + * + * If you are a user or system administrator, rather than software engineer, + * you should read BIND10 Guide (Administrator Reference for BIND10) instead. + * + * Regardless of your field of expertise, you are encouraged to visit + * BIND10 webpage (http://bind10.isc.org) + * + * @section DNS + * - @subpage DataScrubbing + * + * @section DHCP + * - @subpage dhcpv4 + * - @subpage dhcpv6 + * - @subpage libdhcp + * + * @section misc Miscellaneous topics + * - @subpage LoggingApi + * - @subpage LoggingApiOverview + * - @subpage LoggingApiLoggerNames + * - @subpage LoggingApiLoggingMessages + * - @subpage SocketSessionUtility + * - Documentation warnings and errors + * + * @todo: Move this logo to the right (and possibly up). Not sure what + * is the best way to do it in Doxygen, without using CSS hacks. + * @image html isc-logo.png + */ \ No newline at end of file diff --git a/doc/images/isc-logo.png b/doc/images/isc-logo.png new file mode 100644 index 0000000000..1f7af96870 Binary files /dev/null and b/doc/images/isc-logo.png differ