Library structure

There are three structures or hierarchies in the library:

1. Filesystem hierarchy
2. Module hierarchy (almost identical to filesystem hierarchy)
3. Namespace hierarchy

Filesystem and module hierarchy

• The library is structured into modules and sub-modules, represented by directories.
• Modules are sub-directories of the top-level include directory.
• Sub-modules are all sub-directories of module directories with the exception of sub-folders called detail (see below).
• Modules and sub-modules may contain a detail folder that does not constitute a sub-module, it belongs to the (sub-)module it is in and contains implementation detail (all headers inside are not part of the API / may change at any time).
• There are no sub-sub-modules, a third level folder is only allowed, if it is a detail folder.
• All (sub-)modules must provide a "meta-header", called all.hpp.
  • The meta-header includes all headers of the module (except those with _detail in their name) and all of its sub-modules' meta-headers (but not explicitly any content from a detail sub-directory).
  • Unless otherwise required the order of includes shall be alphabetical with sub-modules before files [this is also the filesystem's order]
  • There is a top-level "meta-header" that includes all modules.
  • The meta-header defines a doxygen module of it's name for the documentation.
  • Library headers should never include all.hpp from other (sub-)modules, always include exactly the header required.
• All documented entities that are not members (files, free functions, classes...) shall set the documentation property \ingroup MODULENAME to their respective (sub-)module, i.e. the name of the folder they are in, except where this is called detail (in that case it is it's parent).

Example

seqan3/alphabet/aminoacid/all.hpp   // meta-header of the aminoacid sub-module of the alphabet module
seqan3/alphabet/aminoacid/...       // aminoacid sub-module of the alphabet module
seqan3/alphabet/.../...             // other sub-modules
seqan3/alphabet/detail/...          // implementation detail of the alphabet module
seqan3/alphabet/.../...             // other sub-modules
seqan3/alphabet/all.hpp             // meta-header of the alphabet module
seqan3/alphabet/...                 // alphabet module
seqan3/.../...                      // other modules and sub-modules
seqan3/all.hpp                      // global meta-header that provides all of the API

Namespaces

SeqAn namespaces

• namespace seqan3: everything, except the following exceptions
• namespace seqan3::detail: all free/global functions, metafunctions, static variables and class definitions that are considered implementation detail and not part of the API (and not a private/protected member of a class)
• namespace seqan3::view: seqan-defined views (usually in seqan3/range/view)
• namespace std: overloads of std:: functions like std::begin (rarely)
• nothing should be in the global namespace
• never have using namespace ... in a header file, except inside the test framework

Syntax

• braces go on newline
• closing braces shall be documented
• there is no indention!
• for better readability and because we don't indent, nested namespaces are not declared inside parent, but separately and with full name

Example

namespace seqan3::detail
{

void my_non_public_function()
{
   // ...
}

} // namespace seqan3::detail 

namespace seqan3
{

void my_public_function()
{
    detail::my_non_public_function();
    // ...
}

} // namespace seqan3