Merge branch 'master' into Issue5

Author: rwdougla

config/spellcheck/ignored_words.txt

@@ -1,12 +1,19 @@
 args
+asm
+baz
 Bjarne
+bool
 checkmark
+coe
 constexpr
 cppreference
 Engelhart
+enum
 EPUB
 errno
 expr
+explorative
+extern
 Florian
 func
 Furst
@@ -16,8 +23,11 @@ Hyland
 JC
 Krathwohl
 ness
+nothrow
 NRVO
+RAII
 req
+Rethrowing
 RVO
 Sattler
 SG

config/spellcheck/wordlist

@@ -1,5 +1,6 @@
-personal_ws-1.1 en 18
 ABI
+API
+APIs
 boolean
 computable
 destructors
@@ -10,6 +11,7 @@ metaprogramming
 namespace
 namespaces
 ODR
+personal_ws-1.1 en 18
 preprocessor
 redeclarations
 SFINAE

sources/knowledge_areas.dat

@@ -12,7 +12,8 @@ P Preprocessor
 	? ? ? ? Macros
 B Basics Types, Objects, Values, Expressions, Statements, and Control-Flow Constructs
 	? ? ? ? Constant Objects
-	? ? ? ? Declarations and Definitions
+	? ? ? ? Declarations
+	def y y y Definitions
 	? ? ? ? Selection Constructs (e.g., if, ternary)
 	? ? ? ? Looping Constructs (e.g., for, while, etc.)
 F Functions
@@ -50,10 +51,10 @@ T Generic Programming (Templates)
 	? ? ? ? Requires Clauses
 	req-expr y y n Requires Expressions
 EH Error Handling
-	? ? ? ? Classes of Errors
+	coe y y n Categories of Errors
 	? ? ? ? errno
 	? ? ? ? Error Codes
-	? ? ? ? Exception Handling
+	eh y y y Exception Handling
 SL Standard Library
 	? ? ? ? Input/Output (I/O)
 	? ? ? ? Containers, Iterators, and Algorithms

sources/modules/compilation-model/linkage.md

@@ -0,0 +1,6 @@
+## C++ compilation model: Linkage {#linkage}
+
+_Skeleton descriptions are typeset in italic text,_
+_so please don't remove these descriptions when editing the topic._
+
+This topic is currently under construction and will soon be filled with information :)

sources/modules/compilation-model/translation-units.md

@@ -0,0 +1,6 @@
+## C++ compilation model: Translation units {#translunits}
+
+_Skeleton descriptions are typeset in italic text,_
+_so please don't remove these descriptions when editing the topic._
+
+This topic is currently under construction and will soon be filled with information :)

sources/modules/error-handling/c-style-error-codes.md

@@ -0,0 +1,6 @@
+## Error handling: C-style error codes {#cerrcodes}
+
+_Skeleton descriptions are typeset in italic text,_
+_so please don't remove these descriptions when editing the topic._
+
+This topic is currently under construction and will soon be filled with information :)

sources/modules/error-handling/categories-of-errors.md

@@ -0,0 +1,114 @@
+## Error handling: Categories of errors
+
+_Skeleton descriptions are typeset in italic text,_
+_so please don't remove these descriptions when editing the topic._
+
+### Overview
+
+_Provides a short natural language abstract of the module’s contents._
+_Specifies the different levels of teaching._
+
+------------------------------------------------------------------------
+Level             Objective
+----------------- ------------------------------------------------------
+Foundational      Categories of errors
+
+Main              Handling different categories of errors
+
+Advanced          ---
+
+------------------------------------------------------------------------
+
+### Motivation
+
+_Why is this important?_
+_Why do we want to learn/teach this topic?_
+
+Programs can run in a normal state or erroneous state. Students should be able
+to identify different types of erroneous state and how to best handle them.
+
+### Topic introduction
+
+_Very brief introduction to the topic._
+
+This topic is an umbrella topic that refers to the different topics for types of errors and error handling.
+
+### Foundational: Categories of errors {#coe-found}
+
+#### Background/Required Knowledge
+
+A student:
+
+* should know the basics about linkage [[C++ compilation model: Linkage - Foundational]][1]
+
+#### Student outcomes
+
+_A list of things "a student should be able to" after the curriculum._
+_The next word should be an action word and testable in an exam._
+_Max 5 items._
+
+A student should be able to:
+
+1. Describe different kinds of errors and exceptional situations that require different approaches of error handling.
+2. Provide some examples of the different error categories.
+3. Identify potential erroneous code sections and attribute them to different error categories.
+
+
+#### Caveats
+
+_This section mentions subtle points to understand, like anything resulting in
+implementation-defined, unspecified, or undefined behavior._
+
+No caveats at present.
+
+#### Points to cover
+
+_This section lists important details for each point._
+
+Errors can happen at different times during software lifetime.
+
+* Compile-time errors
+* Link-time errors
+* Execution-time errors
+
+There are different types of errors
+
+* Logic errors (violations of logical preconditions)
+* Run-time errors (errors during code execution due to causes that are external to the program)
+
+
+### Main: Handling different categories of errors {#coe-main}
+
+#### Background/Required Knowledge
+
+#### Student outcomes
+
+A student should be able to:
+
+1. pick the right error handling approach for a given problem.
+2. enumerate different error handling strategies.
+3. make a clear distinction between error-handling code and normal-case handling code
+
+
+#### Caveats
+
+* The different error handling strategies have different trade-offs (runtime performance, readability, ...)
+* The trade-off space depends on the run-time context (embedded, ...)
+* There also exist unhandleable errors (e.g., ODR violations, undefined behavior)
+
+#### Points to cover
+
+* Exception handling [[Error handling: Exception handling - Foundational]][2]
+* Returning a value indication failure [[Error handling: C-style error-codes - Foundational]][3]
+* Terminating the program
+* Improving error handling by having the error occur at an earlier stage in the software development cycle [[Error handling: Static assert - Foundational]][4]
+
+### Advanced {#coe-advanced}
+
+_These are important topics that are not expected to be covered but provide
+guidance where one can continue to investigate this topic in more depth._
+
+[1]: ../compilation-model/linkage.md
+[2]: ../error-handling/exception-handling.md
+[3]: ../error-handling/c-style-error-codes.md
+[4]: ../error-handling/static-assert.md

sources/modules/error-handling/error-codes.md

@@ -0,0 +1,99 @@
+## Error handling: Error codes {#ecodes}
+
+_Skeleton descriptions are typeset in italic text,_
+_so please don't remove these descriptions when editing the topic._
+
+### Overview
+
+_Provides a short natural language abstract of the module’s contents._
+_Specifies the different levels of teaching._
+
+------------------------------------------------------------------------
+Level             Objective
+----------------- ------------------------------------------------------
+Foundational      Handling error codes with `std::error_code`
+
+Main              Designing APIs around `std::error_code`
+
+Advanced          ---
+
+------------------------------------------------------------------------
+
+### Motivation
+
+_Why is this important?_
+_Why do we want to learn/teach this topic?_
+
+C++ offers a type safe way of passing around errors, contrary to the C-style of error handling, by this, we prevent bugs when passing error codes.
+Furthermore, error handling with error codes is more commonly used than exception handling, which only should be used in exceptional situations and in some environments is not feasible at all, e.g., in embedded or performance critical software.
+
+### Topic introduction
+
+_Very brief introduction to the topic._
+
+C++ offers `std::error_code`, which encapsulates error codes in a type safe way.
+This topic describes how to use these error codes.
+
+### Foundational: Handling error codes with `std::error_code` {#eh-found}
+
+#### Background/Required Knowledge
+
+A student:
+
+* should know that there are different ways of error handling [[Error handling: Categories of errors]][1]
+* should know function return values
+
+#### Student outcomes
+
+_A list of things "a student should be able to" after the curriculum._
+_The next word should be an action word and testable in an exam._
+_Max 5 items._
+
+A student should be able to:
+
+1. write code to handle errors with `std::error_code`, e.g., obtain the message of the error code or check if an error occurred.
+2. distinguish between the different categories and make justified decisions when to use which
+
+#### Caveats
+
+_This section mentions subtle points to understand, like anything resulting in
+implementation-defined, unspecified, or undefined behavior._
+
+#### Points to cover
+
+_This section lists important details for each point._
+
+* a brief overview of `std::error_code` and how to use it
+
+### Main: Designing APIs around `std::error_code` {#eh-main}
+
+#### Background/Required Knowledge
+
+* should know how to use reference parameters as an output parameter
+
+#### Student outcomes
+
+A student should be able to:
+
+1. create an `error_code` and design API that work with `std:error_code`
+2. write code that utilizes `std::error_category`
+3. explain the difference between C-style error handling with errno and `std::error_code`
+4. make effective use of the interface of `std::error_code`
+
+#### Caveats
+
+* reset errno before calling a function that might set errno (better pass an input parameter `std::error_code`)
+
+#### Points to cover
+
+* provide a full picture of `std::error_code` and it’s APIs
+* `std::error_category` (explorative)
+
+### Advanced
+
+_These are important topics that are not expected to be covered but provide
+guidance where one can continue to investigate this topic in more depth._
+
+* implementing your own `error_category`
+
+[1]: error-handling/categories-of-errors.md