[3396] Small changes to .dox files made during review

diff --git a/doc/devel/contribute.dox b/doc/devel/contribute.dox
index c71e632f34959a88849c08232d845bda42470664..d1b67aa4ea9d2198cac64d12e0e5c2dfd3ca2bdc 100644 (file)
--- a/doc/devel/contribute.dox
+++ b/doc/devel/contribute.dox
@@ -26,12 +26,14 @@ Before you start working on a patch or a new feature, it is a good
 idea to discuss it first with Kea developers. You can post your
 questions to the \c kea-dev mailing list
 (https://lists.isc.org/mailman/listinfo/kea-dev) or kea-users
-(https://lists.isc.org/mailman/listinfo/kea-users). Kea-users list
-is intended for users who are not interested in the internal working
-or development details. It is ok to ask for feedback regarding new
+(https://lists.isc.org/mailman/listinfo/kea-users). The kea-users list
+is intended for users who are not interested in the internal workings
+or development details of Kea: it is OK to ask for feedback regarding new
 design or the best proposed solution to a certain problem, but all
-the internal details should be limited to kea-dev and not posted
-on kea-users. If you prefer to get
+the internal details should be discussed on kea-dev and not posted
+to kea-users.
+
+If you prefer to get
 faster feedback, most Kea developers hang out in the \c dhcp
 jabber room (xmpp:dhcp@conference.jabber.isc.org). Feel free to join this
 room and talk to us. It is possible that someone else is working on your
@@ -39,17 +41,17 @@ specific issue or perhaps the solution you plan to implement is not
 the best one. Often having a 10 minute talk could save many hours of
 engineering work.
 
-First step would be to get the source code from our Git repository. The
-procedure is very easy and is explained here:
-http://kea.isc.org/wiki/GitGuidelines.  While it is possible to
-provide a patch against the latest stable release, it makes the review
-process much easier if it is for latest code from the Git \c master
-branch.
+The first step in writing the patch or new feature should be to get
+the source code from our Git repository. The procedure is very easy and
+is explained here: http://kea.isc.org/wiki/GitGuidelines.  While it is
+possible to provide a patch against the latest stable release, it makes
+the review process much easier if it is for latest code from the Git \c
+master branch.
 
-Ok, so you have written a patch? Great! Before you submit it, make sure
+OK, so you have written a patch? Great! Before you submit it, make sure
 that your code compiles. This may seem obvious, but there's more to
 it. You have surely checked that it compiles on your system, but Kea
-is a portable software. Besides Linux, it is compiled and used on
+is portable software. Besides Linux, it is compiled and used on
 relatively uncommon systems like OpenBSD and Solaris 11. Will your code
 compile and work there? What about endianess? It is likely that you used
 a regular x86 architecture machine to write your patch, but the software
@@ -59,8 +61,8 @@ For a complete list of systems we build on, you may take a look at the
 following build farm report: http://git.kea.isc.org/~tester/builder/KEA-builder-new.html .
 
 Does your patch conform to Kea coding guidelines
-(http://kea.isc.org/wiki/CodingGuidelines)? You still can submit a
-patch that does not adhere to it, but that will decrease its chances of
+(http://kea.isc.org/wiki/CodingGuidelines)? You can submit a
+patch that does not adhere to them, but that will reduce its chances of
 being accepted. If the deviations are minor, the Kea engineer who
 does the review will likely fix the issues. However, if there are lots
 of issues, the reviewer may simply reject the patch and ask you to fix
@@ -71,8 +73,8 @@ it before re-submitting.
 One of the ground rules in Kea development is that every piece of
 code has to be tested. We now have an extensive set of unit-tests for
 almost every line of code. Even if you are fixing something small,
-like a single line fix, it is encouraged to write unit-tests for that
-change. That is even more true for new code. If you write a new
+like a single line fix, you are encouraged to write unit-tests for that
+change. That is even more true for new code: if you write a new
 function, method or a class, you definitely should write unit-tests
 for it.
 
@@ -118,11 +120,11 @@ checks on logger parameters. Use \c --enable-debug to enable various
 additional consistency checks that reduce performance but help during
 development. If you happen to modify anything in the
 documentation, use \c --enable-generate-docs. If you are modifying DHCP
-code, you are likely to be interested in enabling the MySQL backend for
-DHCP. Note that if the backend is not enabled, MySQL specific unit-tests
-are skipped. From that perspective, it is useful to use
-\c --with-dhcp-mysql. For PostgreSQL, use \c --with-dhcp-pgsql. For a
-complete list of all switches, use:
+code, you are likely to be interested in enabling a database backend for
+DHCP. Note that if the backend is not enabled, the database-specific unit-tests
+are skipped. To enable the MySQL backend, use the switch
+\c --with-dhcp-mysql; for PostgreSQL, use \c --with-dhcp-pgsql.
+A complete list of all switches can be obtained with the command:
 
 @code
  ./configure --help
@@ -130,7 +132,7 @@ complete list of all switches, use:
 
 @section contributorGuideReview Going through a review
 
-Once all those are checked and working, feel free to create a ticket for
+Once everything is checked and working, feel free to create a ticket for
 your patch at http://kea.isc.org/ or attach your patch to an existing
 ticket if you have fixed it. It would be nice if you also join the
 \c dhcp chatroom saying that you have submitted a patch. Alternatively,
@@ -143,12 +145,12 @@ take a while sometimes. Having said that, we value external
 contributions very much and will do whatever we can to review patches in
 a timely manner. Don't get discouraged if your patch is not accepted
 after first review. To keep the code quality high, we use the same
-review processes for internal code and for external patches. It may take
+review processes for external patches as we do for internal code. It may take
 some cycles of review/updated patch submissions before the code is
 finally accepted. The nature of the review process is that it emphasizes
 areas that need improvement. If you are not used to the review process,
-you may get the impression that the feedback is negative. It is not. We
-seldom see reviews that say "all ok, please merge".
+you may get the impression that the feedback is negative. It is not: even
+the Kea developers seldom see reviews that say "All OK please merge".
 
 Once the process is almost complete, the developer will likely ask you
 how you would like to be credited. The typical answers are by first and
@@ -163,7 +165,7 @@ If you are interested in knowing the results of more in-depth testing,
 you are welcome to visit the Kea build farm:
 http://git.kea.isc.org/~tester/builder/KEA-builder-new.html.  This is a
 live result page with all tests being run on various systems.  Besides
-basic unit-tests, we also have reports from Valgrind (memory debugger),
+basic unit-tests, we also have reports from valgrind (memory debugger),
 cppcheck and clang-analyzer (static code analyzers), Lettuce system
 tests and more. Although it is not possible for non ISC employees to run
 tests on that farm, it is possible that your contributed patch will end

diff --git a/src/lib/dhcpsrv/libdhcpsrv.dox b/src/lib/dhcpsrv/libdhcpsrv.dox
index e7942cc07fe41c63235a00aed5d85bfda3dc068c..625cedb112377549c3e43b00a833ab5621314a67 100644 (file)
--- a/src/lib/dhcpsrv/libdhcpsrv.dox
+++ b/src/lib/dhcpsrv/libdhcpsrv.dox
@@ -43,7 +43,7 @@ Configuration Manager (\ref isc::dhcp::CfgMgr) stores configuration information
 necessary for DHCPv4 and DHCPv6 server operation. In particular, it stores
 subnets (\ref isc::dhcp::Subnet4 and \ref isc::dhcp::Subnet6) together with
 their pools (\ref isc::dhcp::Pool4 and \ref isc::dhcp::Pool6), options and
-other information specified by the used in Kea configuration.
+other information specified by the user in the Kea configuration.
 
 @section allocengine Allocation Engine
 

diff --git a/src/lib/hooks/hooks_component_developer.dox b/src/lib/hooks/hooks_component_developer.dox
index ee7b99716cf0d81c95b037402ebf0e8d9d2c92df..ef469a44cfa1195b87ccd35c2bf145c555a420dc 100644 (file)
--- a/src/lib/hooks/hooks_component_developer.dox
+++ b/src/lib/hooks/hooks_component_developer.dox
@@ -21,7 +21,7 @@ The hooks framework is a Kea system that simplifies the way that
 users can write code to modify the behavior of Kea.  Instead of
 altering the Kea source code, they write functions that are compiled
 and linked into a shared library.  The library is specified in the Kea
-configuration and during run time Kea dynamically loads the library
+configuration and at run time Kea dynamically loads the library
 into its address space.  At various points in the processing, the component
 "calls out" to functions in the library, passing to them the data is it
 currently working on.  They can examine and modify the data as required.
@@ -37,7 +37,7 @@ during its execution, see the document @ref hooksdgDevelopersGuide.
 
 In the remainder of this guide, the following terminology is used:
 
-- Component - a Kea process, e.g. a DHCPv4 or DHCPv6 server.
+- Component - a Kea process, e.g. the DHCPv4 or DHCPv6 server.
 
 - Hook/Hook Point - used interchageably, this is a point in the code at
 which a call to user-written functions is made. Each hook has a name and

diff --git a/src/lib/hooks/hooks_user.dox b/src/lib/hooks/hooks_user.dox
index 7071696c28c976b3cee53b3c7b88898790a411e2..6f9954ba7beccc869b86d1c24c88fcbf001cc4f0 100644 (file)
--- a/src/lib/hooks/hooks_user.dox
+++ b/src/lib/hooks/hooks_user.dox
@@ -133,7 +133,7 @@ Although the hooks system allows Kea and user code to interface
 through a defined API, the relationship is somewhat tight in that the
 user code will depend on the internal structures of Kea.  If these
 change - as they can between Kea releases - and Kea is run with
-a version of user code built against an earlier version of Kea, program
+a version of user code built against an earlier version of Kea, a program
 crash could result.
 
 To guard against this, the "version" function must be provided in every

diff --git a/src/lib/log/logging.dox b/src/lib/log/logging.dox
index f10685013d4fec4bbf5eb35743ff015bc8b6faf4..dc9c1a7729264b6f3b6b27ed08f23aa39dd12af3 100644 (file)
--- a/src/lib/log/logging.dox
+++ b/src/lib/log/logging.dox
@@ -285,8 +285,8 @@ a problem in a write operation.</li>
 two or three words separated by underscores.  An excessive number
 of words or overly long message identification should be avoided;
 such information should be put in the text of the message.  For example,
-"RESOLVER_ERROR_FETCHING_NAME_FROM_UPSTREAM_SERVER" is excessively long,
-"RESOLVER_FETCH_ERROR" being better.</li>
+"RECEIVED_EMPTY_HOSTNAME_FROM_CLIENT" is excessively long,
+"EMPTY_HOSTNAME" being better.</li>
 
 <li>Similarly, the text of the message should be reasonably concise.  It should
 include enough information (possibly supplied at run-time in the form of