wip system_error coverage

annotations/yo/advancedtemplates.yo

@@ -67,11 +67,11 @@ includefile(advancedtemplates/trait)
     lsubsect(TYPETRAITS)(Available type traits)
     includefile(advancedtemplates/availabletraits)
 
-    lsubsect(ERRCODEENUM)(Defining your own enum for std::error_code)
-    includefile(advancedtemplates/errcodeenum)
+    lsubsect(ERRCODEENUM)(Deriving classes from std::error_code)
+    includefile(advancedtemplates/errorcode)
 
-    lsubsect(ERRCONDITONENUM)(Defining your own enum for std::error_condition)
-    includefile(advancedtemplates/errconditionenum)
+    lsubsect(ERRCONDITIONENUM)(Deriving classes from std::error_condition)
+    includefile(advancedtemplates/errorcondition)
 
 lsect(NOEXCEPT)(Using `noexcept' when offering the `strong guarantee')
 includefile(advancedtemplates/noexcept)

annotations/yo/advancedtemplates/errorcode.yo

@@ -1,5 +1,5 @@
 In section ref(ERRORCODEEXC) the class tt(std::error_code) was introduced. One
-of its constructors accepts an tt(ErrorCodeEnum), which may be an tt(enum) we
+of its constructors accepts an ti(ErrorCodeEnum), which may be an tt(enum) we
 define ourselves. Standard error code values (like the tt(errno) values, or
 the values defined by tt(enum class Errc) are used by low-level system
 functions like bf(stat)(2), but none may be available or suited for errors

annotations/yo/exceptions/errorcategory.yo

@@ -1,15 +1,15 @@
 Objects of classes derived from the base class tt(std::error_category)
-(cf. section ref(ERRCAT)) identify the source and encoding of a particular
-category of error codes.
+(cf. section ref(ERRCAT)) identify the source of a group of error
+codes. Usually error categories are defined for new tt(ErrorCodeEnums)
 
 In addition to the standard available tt(error_category) classes new
 tt(error_category) classes may be derived from tt(std::error_category) which
-can then be used as a tailor-made tt(error_category) to be used by 
-tt(system_error) constructors.
+can then be used as tailor-made error categories by tt(system_error)
+constructors.
 
-Error categories are designed as em(Singletons): only one object of each class
-may exist. Therefore the equality of tt(error_category) objects can be deduced
-from the equality of their addresses. 
+Error categories should be designed as em(Singletons): only one object of each
+class should exist. By using singletons the equality of tt(error_category)
+objects can simply be deduced from the equality of their addresses.
 
 tt(Error_category) classes offer the following members:
     itemization(
@@ -21,19 +21,19 @@ tt(Error_category) classes offer the following members:
 
     ithtq(default_error_condition)
         (error_condition default_error_condition(int ev) const noexcept)
-       (returns an object of type tt(error_condition) corresponding to the
-        error value tt(ev). Error conditions are platform-independent
-        (portable) error codes (see the next section);)
+       (returns the tt(error_condition) corresponding to the error value
+        tt(ev) as defined in the current tt(error_category);)
 
     ithtq(equivalent)
        (bool equivalent(int ev, error_condition const &condition) const
             noexcept)
-       (returns tt(true) if error value `tt(ev)' is considered equivalent to
-        tt(error_condition condition);)
+       (returns tt(true) if error value tt(ev's) error condition is equal to
+        tt(condition);)
 
-    ittq(bool equivalent(error_code const &code, int value) const noexcept)
-       (returns tt(true) if tt(error_code code) is considered equivalent to
-        tt(value);)
+    ittq(bool equivalent(error_code const &code, int condition) const noexcept)
+       (returns tt(true) if tt(code's) error category is equal to the current
+        category and tt(code's) error condition is equal to 
+        tt(condition);)
 
     ittq(bool operator<(error_category const &rhs) const noexcept)
        (returns tt(less<const error_category*>()(this, &rhs)).)

annotations/yo/exceptions/errorcode.yo

@@ -1,17 +1,16 @@
-Error code objects are used by tt(error_category) or tt(system_error)
-objects. E.g., some constructors of tt(system_error) accept
-tt(std::error_code) hi(error_code) objects. 
+tt(Error_code) objects are used by tt(error_category) or tt(system_error)
+objects. E.g., some tt(system_error) constructors accept tt(std::error_code)
+hi(error_code) objects.
 
-The main purpose of tt(error_code) objects is to encapsulate platform
-dependent em(error code values), as determined by the operating system or
-comparable low-level functions (like bf(chmod)(2)), Error code values are
-commonly assigned by such functions to tt(errno). 
+The main purpose of tt(error_code) objects is to encapsulate 
+em(error values), and associated em(error categories). Often, error values
+become available as values assigned to the global tt(int errno).
 
-In addition, an tt(error_category) defining the encountered error's general
-category (see the next section) is usually specified when constructing an
+In addition, an tt(error_category) is used to specify an encountered error's
+category (see the next section). It is usually specified when constructing an
 tt(error_code) object.
 
-The class tt(error_code) provides the following public interface and free
+The class tt(error_code) has the following public interface and free
 functions:
 
 bf(Constructors):
@@ -29,11 +28,11 @@ bf(Constructors):
          em(category) (e.g., tt(&system_category()) or
          tt(generic_category()));)
 
-    ittq(error_code(ErrorCodeEnum e) noexcept)
+    ittq(error_code(ErrorCodeEnum value) noexcept)
        (this is a member template (cf. section ref(MEMTEMP)), using template
         header tt(template <class ErrorCodeEnum>). It initializes the object
-        with the return value of tt(make_error_code(e)). In section
-        ref(ERRCODEENUM) defining your own tt(ErrorCodeEnum) is covered; )
+        with the return value of tt(make_error_code(value)). In section
+        ref(ERRCODEENUM) defining an tt(ErrorCodeEnum) is covered; )
     )
 
 bf(Members):
@@ -70,14 +69,14 @@ bf(Free functions):
     it() Two tt(error_code) objects can be compared for (in) equality and can
         be ordered (using tt(operator<));
 
-    ittq(error_code make_error_code(errc e) noexcept)
-       (returns tt(error_code(static_cast<int>(e), generic_category()))
+    ittq(error_code make_error_code(errc value) noexcept)
+       (returns tt(error_code(static_cast<int>(value), generic_category()))
         (tt(errc: see below));)
 
     ittq(std::ostream &operator<<(std::ostream & os, error_code const &ec))
-       (inserts the following text into tt(os):
+       (executes the following statement:
     verb(
-os << ec.category().name() << ':' << ec.value().
+return os << ec.category().name() << ':' << ec.value();
         ))
     )
 

annotations/yo/exceptions/errorcondition.yo

@@ -1,16 +1,11 @@
-tt(Error_condition)hi(error_condition) objects represent platform independent
-error codes (comparable to the platform dependent error codes represented by
-tt(error_code) objects).
+tt(Error_condition)hi(error_condition) objects provide information about the
+causes of errors, like user input error, permission errors or system function
+failures. As such error causes are not restricted to specific platforms, they 
+are representing platform independent categories.
 
-Error conditions can be used as `super error codes' extending the scopes of
-error codes by, e.g., combining codes that are used (differently) by different
-operating systems. Somewhat comparable to using functions like bf(htons)(3)
-and bf(ntosh)(3) to convert system dependent endianess to the (operating
-system independent) network byte order.
-
-Error condition objects are returned by the tt(default_error_condition)
-members of the classes tt(error_code) and tt(error_category), and are expected
-as argument of tt(error_category::equivalent).
+Error condition objects are returned by tt(default_error_condition) members of
+tt(error_code) and tt(error_category) classes, and are expected as argument of
+the member tt(error_category::equivalent).
 
 The class tt(error_condition) offers the following (public) interface:
 
@@ -19,13 +14,13 @@ bf(Constructors):
     ittq(error_condition() noexcept)
        (the default constructor initializes the error code with an error
         em(value) 0 and a tt(system_category) error category. Error value 0 is
-        normally not considered an error;)
+        not considered an error;)
 
     it() The copy constructor is available;
 
     ittq(error_condition(int ec, error_category const &cat) noexcept)
        (this constructor initializes the error condition with error value
-        tt(ec), and an error em(category);)
+        tt(ec), and error category tt(cat);)
 
     ittq(error_condition(ErrorConditionEnum e) noexcept)
        (this is a member template (cf. section ref(MEMTEMP)), using template

annotations/yo/exceptions/systemerror.yo

@@ -1,15 +1,34 @@
 The class ti(std::system_error) is derived from
-tt(std::runtime_error). tt(System_error) objects can be thrown when an error
-occurs that has an associated (system) error code and error category. Such
-errors are typically associated with low-level (like operating system)
-functions.
+tt(std::runtime_error). 
 
 Before using the class tt(system_error) or related classes the
 tthi(system_error) header file must be included.
 
+tt(System_error) objects can be thrown when errors are
+encountered having associated (system) em(error values). Such errors are
+typically associated with low-level (like operating system) functions, but
+other types of error (e.g., bad user input, non-existing requests) can also be
+handled. Error codes are objects storing error values and matching
+categories. Such categories define domains to which error codes
+belong. In practice this means that a series of error codes is defined in an
+enum, and that a unique category is associated with that enum. New enums and
+associated categories may then be defined, and enum values may be
+identical across different enums, as their categories can be used, like
+name spaces, to avoid confusion. One of the reasons for using categories
+is that enums don't support inheritance: inside tt(error_code) objects they
+are stored as tt(int) values, losing the original  enum category.
+
+In addition to error codes and categories error em(conditions) are
+distinguished. Error conditions are associated with causes of errors, like bad
+user input, failing system functions or non-existing requests. Error 
+conditions are considered platform independent (as in: users provide bad input
+on all kinds of platforms) whereas error codes and error categories are
+tailored to programs that are actually being used.
+
 When constructing tt(system_error) objects tt(error_codes) and
-tt(error_categories) may be specified. These classes are now introduced, after
-which tt(system_error) itself is covered in more detail.
+tt(error_categories) may be specified. These latter two classes as well as
+tt(error_condition) are now first introduced, after which tt(system_error)
+itself is covered in more detail.
 
 Figure ref(SYSERRFIG) illustrates how the various components used by
 tt(system_error) interact.
@@ -21,25 +40,16 @@ tt(system_error) interact.
 As tt(system_error) is eventually derived from tt(exception) it offers the
 standard tt(what) member. Its other data element is an
 tt(error_code). tt(Error_codes) can be constructed from tt(int) values, but
-also from a separately defined tt(ErrorCodeEnum). tt(Error_codes) are
-associated with tt(error_categories), representing a group of tt(error_code)
-values. Different tt(error_categories) may use identical tt(error_code) values,
-which are then distinguished by their tt(error_category. Error_codes)
-represent platform dependent error values. 
+also from separately defined tt(ErrorCodeEnums). Since tt(error_codes) are 
+associated with tt(error_categories) an tt(error_category) must be provided
+when tt(int) error values are available.
 
-When multiple tt(error_code) enums are used (the enums could be defined on
-different platforms), em(error_conditions) can be defined allowing you to
-group, classify, or translate tt(error_code) values (between different
-platforms). Defining an tt(error_condition) is covered in section
-ref(ERRCONDITONENUM).
-
-In POSIX systems the tt(errno) variable may be associated with many, rather
-cryptic symbols, and the predefined tt(enum class errc) is an attempt to use
-intuitively more appealing symbols instead. Since its symbols are defined in a
-strongly typed enumeration, they cannot directly be used when defining a
-matching tt(error_code). Instead, the function tt(make_error_code) converts
-tt(enum class errc) values to tt(int) values, so they can be used when
-constructing tt(error_code) objects.
+In POSIX systems the tt(errno) variable may be associated with many, often
+rather cryptic, symbols. The predefined tt(enum class errc) is an attempt to
+use intuitively more appealing symbols instead. Since its symbols are defined
+in a strongly typed enumeration, they cannot directly be used when defining a
+matching tt(error_code). Instead, a function tt(make_error_code) is available,
+converting tt(enum class errc) values to tt(error_code) objects.
 
 Now that the general outline has been presented, it's time to have a closer
 look at the various components shown in figure ref(SYSERRFIG).

annotations/yo/exceptions/systemerroruse.yo

@@ -36,8 +36,8 @@ set of three constructors. E.g.,
     system_error(error_code(errno, system_category()), 
                                             "context of the error");
         )
-    However, the second set of three constructors are of course usually used
-when an existing function already returns an tt(error_code). E.g.,
+    The second set of three constructors are primarily used when an existing
+function already returns an tt(error_code). E.g.,
         verb(
     system_error(make_error_code(errc::bad_address), 
                                             "context of the error");
@@ -60,7 +60,24 @@ Note that, although tt(system_error) was derived from tt(runtime_error),
 you'll lose the tt(code) member when catching a tt(std::exception) object. Of
 course, downcasting is always possible, but that's a stopgap. Therefore, if a
 tt(system_error) is thrown, a matching tt(catch(system_error const &)) clause
-should be provided (for a flexible alternative, see the class 
+must be provided to retrieve the value returned by the tt(code) member. This,
+and the rather complex organization of the classes that are involved when
+using tt(system_error) result in a very complex, and hard to generalize
+exception handling. In essence, what you obtain at the expense of high
+complexity is a facility for categorizing tt(int) or tt(enum) error
+values. More in-dept coverage of the involved complexities is provided in
+chapter ref(ADVANCEDTEMPL), in particular sections ref(ERRCODEENUM) and
+ref(ERRCONDITIONENUM)) (for a flexible alternative, see the class 
     hi(Exception (Bobcat)) tt(FBB::Exception) in the author's 
         url(Bobcat library)(http://fbb-git.github.io/bobcat/).\
         hi(Bobcat library)hi(http://fbb-git.github.io/bobcat/))
+
+
+
+
+
+
+
+
+
+