// vim:ft=doxygen
/**

\defgroup pbdrv pbdrv
\brief Standalone puzzle bus driver

\ref pbdrv is a standalone portable static library for handling (i.e.
(de)serialization) of puzzle bus messages. \ref pbdrv is meant for use within
applications that handle puzzle bus messages, but are not puzzle modules
themselves. For a complete puzzle module driver, please see \ref pbdrv-mod.

If you order to use \ref pbdrv, you need to include this folder in your
CMakeLists.txt file, include the \ref pb_ext "extension" for your target
platform, and link the \c pbdrv library with your executable.

\par Example
```cmake
# include pbdrv
add_subdirectory(lib/pbdrv)

# <use extension>

# link with executable
target_link_libraries(main pbdrv)
```


\defgroup pbdrv-mod pbdrv-mod
\brief Puzzle module driver (superset of \ref pbdrv)

pbdrv-mod is a superset of \ref pbdrv, and includes functions specific to
puzzle bus modules. \ref pbdrv-mod compiles to an object file instead of a
static library because it may depend on functions from external libraries. \ref
pbdrv-mod is still considered standalone, but requires either using an existing
\ref pb_drv "driver", or (partially) implementing the driver functions.

Like \ref pbdrv, \ref pbdrv-mod can be used by including this folder in your
CMakeLists.txt file and linking the library with your executable. Please see
the \ref pb_drv "drivers" page for target-specific usage instructions.

\par Example
```cmake
# include pbdrv
add_subdirectory(lib/pbdrv)

# link with executable
target_link_libraries(main pbdrv-mod)
```

\note In most cases, the \ref pb_hook "hooks" should be sufficient to realize
extensions or custom behavior not provided by \ref pbdrv-mod.

\note Most \c pb_* functions have a weak implementation, which may be
overwritten by a custom implementation. This allows you to use the default
implementation where possible, and only implement extensions required for your
puzzle module.

\see pbdrv

\{

\defgroup pb_hook Hook
\brief Functions for (partially) overriding default behavior

Hooks are functions that allow the user to implement custom behavior (i.e.
extend or conditionally replace the default handlers), without needing to
completely overwrite the built-in handlers or understand the internals of \ref
pbdrv-mod.

The boolean value returned by some hooks (e.g. those under \ref pb_hook_route
or \ref pb_hook_i2c) represents if the default handler should run after the
hook returns. This allow you to conditionally 'catch' calls to their respective
base functions by returning \c true.

\}

*/