doc/technical_overview.dox

   1 /**
   2
   3 \page technical_overview Technical Overview
   4
   5 \tableofcontents
   6
   7 \section sec_overview_directory Directory Overview
   8 This section explains the directory structure.
   9
  10 \verbatim
  11 root
  12 +- bin
  13 +- cmake
  14 +- doc
  15 +- examples
  16 +- extern
  17 +- include
  18 |  +- marnav
  19 |     +- ...
  20 +- src
  21 |  +- marnav
  22 |     +- ais
  23 |     +- geo
  24 |     +- io
  25 |     +- math
  26 |     +- nmea
  27 |     +- seatalk
  28 |     +- utils
  29 +- test
  30 \endverbatim
  31
  32 - \c bin      : helper scripts
  33 - \c cmake    : CMake Modules
  34 - \c doc      : Documentation
  35 - \c examples : Examples included in the documentation and build as well.
  36                 This examples use the library to demonstrate its usage.
  37 - \c extern   : External projects and resources used by the library.
  38 - \c test     : All tests
  39 - \c include  : Public headers
  40 - \c src      : Complete source of the library, source and private header files.
  41                 Packages are grouped in their own subdirectory, named
  42                 accordingly (e.g. \c marnav/nmea).
  43
  44 In the directories `src` and `include`:
  45 - \c ais     : all AIS related stuff. Note that despite the AIS builds on
  46                the NMEA protocol (VDM, VDO sentences), the package does not
  47                have any dependencies to the \c nmea package.
  48 - \c geo     : collection of geographic and geodesic functions
  49 - \c io      : input output stuff, mainly for NMEA and SeaTalk. Please note,
  50                that this package is not mandatory. It is perfectly fine
  51                to use the \c nmea package without \c io.
  52 - \c math    : generic math stuff
  53 - \c nmea    : everything NMEA-0183 related
  54 - \c seatalk : everything SeaTalk related, except IO.
  55 - \c utils   : common utils
  56
  57
  58 \section sec_overview_package_dependencies Package dependencies
  59 The directory structure underneath \c src reflects the packages.
  60 Every package has its own namespace.
  61
  62 \dot
  63         digraph G {
  64                 node [shape=record, fonthame=Helvetica, fontsize=10];
  65                 ais -> { geo utils };
  66                 nmea -> { geo utils };
  67                 seatalk -> { utils };
  68                 io -> { nmea seatalk utils };
  69                 geo -> { math };
  70         }
  71 \enddot
  72
  73 Not shown in the picture:
  74 - The standard library
  75 - Unittests (using GoogleTest/GoogleMock)
  76 - Benchmarking (using Google's Benchmark)
  77 - Examples (some of them use boost.asio or Qt5)
  78
  79
  80 \section sec_overview_general General Stuff
  81
  82 The code of the library is quite defensive. This should usually not
  83 be a problem, because the (usual) environment of a library as this
  84 is not high performance. Some additional checks will not hurt too much.
  85
  86
  87 \section sec_overview_naming Naming Conventions
  88
  89 Everything is in small case (types, classes, structs, member functions,
  90 member data, etc.) with underscores (snakes).
  91
  92 There are occasional exceptions of constants in all captial letters.
  93 For the future, this practice is discouraged.
  94
  95 Reason:
  96 - other libraries do this too (std, boost)
  97 - I like it this way
  98
  99
 100 \section sec_overview_formatting Formatting
 101
 102 Code formatting is done using \c clang-format, using the provided
 103 configuration file (\c .clang-format)
 104
 105
 106 \section sec_overview_header_inclusion Order of Header inclusion
 107
 108 In general the order is from system headers to project headers. The
 109 more private, the later the inclusion.
 110
 111 For header files:
 112 - system headers
 113 - thrid party library headers
 114 - marnav headers
 115
 116 For translation units:
 117 - its own header
 118 - system headers
 119 - thrid party library headers
 120 - marnav headers
 121
 122 With the exception of the translation unit's own header file, are all
 123 header included with full qualified path.
 124
 125
 126 */