Update documentation

8 files changed, 154 insertions, 67 deletions

diff --git a/doc/src/extfs.rst b/doc/src/api/extfs.rst
index d8f1f5a..d8f1f5a 100644
--- a/doc/src/extfs.rst
+++ b/doc/src/api/extfs.rst
diff --git a/doc/src/api.rst b/doc/src/api/index.rst
index 3b2cec2..3b2cec2 100644
--- a/doc/src/api.rst
+++ b/doc/src/api/index.rst
diff --git a/doc/src/conf.py b/doc/src/conf.py
index a67aee4..bf3d6b1 100644
--- a/doc/src/conf.py
+++ b/doc/src/conf.py
@@ -9,11 +9,15 @@ subprocess.call('cd ../../ && doxygen', shell=True)
 
 html_theme = 'sphinx_rtd_theme'
 
-extensions = ['breathe']
+extensions = [
+    'breathe',
+    'sphinx.ext.todo',
+]
 
 breathe_projects = {'extfs': os.path.abspath('../../build/xml') }
 breathe_default_project = 'extfs'
 
+
 source_suffix = '.rst'
 master_doc = 'index'
 
@@ -35,7 +39,7 @@ exclude_patterns = [
 
 pygments_style = 'sphinx'
 
-todo_include_todos = False
+todo_include_todos = True
 
 htmlhelp_basename = 'extfsdoc'
 
diff --git a/doc/src/index.rst b/doc/src/index.rst
index dee63dd..9c02bcc 100644
--- a/doc/src/index.rst
+++ b/doc/src/index.rst
@@ -12,4 +12,5 @@ User documentation
 .. toctree::
    :maxdepth: 2
 
-   api
+   api/index
+   internal/index
diff --git a/doc/src/internal/index.rst b/doc/src/internal/index.rst
new file mode 100644
index 0000000..4b7e2f7
--- /dev/null
+++ b/doc/src/internal/index.rst
@@ -0,0 +1,7 @@
+Internal Design
+===============
+
+.. toctree::
+  :maxdepth: 1
+
+  superblock
diff --git a/doc/src/internal/superblock.rst b/doc/src/internal/superblock.rst
new file mode 100644
index 0000000..6e85df4
--- /dev/null
+++ b/doc/src/internal/superblock.rst
@@ -0,0 +1,42 @@
+The Superblock
+==============
+
+The **superblock** of an ext2/3/4 file system describes the structure and
+configuration of the file system. This information is used by the
+implementation to determine the physical and logical structure of the file
+system. This section describes the structure of the superblock itself.
+
+Definitions
+-----------
+
+All fields described in this section are stored on the disk in little-endian
+format, regardless of the system architecture.
+
+.. warning:: The implementation currently only works in little-endian
+  architectures. If you would like to get involved in implementing big-endian
+  support, please file an issue at the project repository over at
+  `Github <https://github.com/fmorgner/extfs>`_
+
+The code in `Implementation`_ makes us of several :code:`using` directives to
+reduce the amount of typing as well as make the code more readable. The
+following aliases are declared in ``fs/detail/types.hpp``:
+
+.. doxygentypedef:: fs::detail::u32
+.. doxygentypedef:: fs::detail::s32
+.. doxygentypedef:: fs::detail::u16
+.. doxygentypedef:: fs::detail::s16
+.. doxygentypedef:: fs::detail::u08
+.. doxygentypedef:: fs::detail::u32_arr
+.. doxygentypedef:: fs::detail::u08_arr
+.. doxygentypedef:: fs::detail::chr_arr
+
+Structure
+---------
+
+.. todo:: Describe structure of the superblock
+
+Implementation
+--------------
+
+.. doxygenstruct:: fs::detail::extfs_superblock
+  :members:
diff --git a/include/fs/detail/superblock.hpp b/include/fs/detail/superblock.hpp
index 5b7a4ca..f86fe3d 100644
--- a/include/fs/detail/superblock.hpp
+++ b/include/fs/detail/superblock.hpp
@@ -1,78 +1,69 @@
 #ifndef EXTFS_SUPERBLOCK_HPP
 #define EXTFS_SUPERBLOCK_HPP
 
+#include "fs/detail/types.hpp"
+
 #include <array>
 #include <cstdint>
 
 namespace fs::detail
   {
 
-  using u32 = std::uint32_t;
-  using s32 = std::int32_t;
-  using u16 = std::uint16_t;
-  using s16 = std::uint16_t;
-  using u08 = std::uint8_t;
-
-  template<std::size_t Size>
-  using chr_arr = std::array<char, Size>;
-
-  template<std::size_t Size>
-  using u08_arr = std::array<u08, Size>;
-
-  template<std::size_t Size>
-  using u32_arr = std::array<u32, Size>;
-
-
+  /**
+   * This structure describes the ext2/3/4 superblock
+   *
+   * @since 1.0
+   */
   struct extfs_superblock
     {
-    u32 const inodes_count{};
-    u32 const blocks_count{};
-    u32 const reserved_blocks_count{};
-    u32 const free_blocks_count{};
-    u32 const free_inodes_count{};
-    u32 const first_data_block_id{};
-    u32 const logical_block_size{};
-    s32 const logical_fragment_size{};
-    u32 const blocks_per_group{};
-    u32 const fragments_per_group{};
-    u32 const inodes_per_group{};
-    u32 const last_mount_timestamp{};
-    u32 const last_write_timestamp{};
-    u16 const mount_count{};
-    u16 const maximum_mount_count{};
-    u16 const magic_number{};
-    s16 const state{};
-    s16 const error_behaviour{};
-    s16 const revision_level_minor{};
-    u32 const last_check_timestamp{};
-    u32 const check_interval{};
-    u32 const creator_operating_system_id{};
-    u32 const revision_level{};
-    u16 const super_user_id{};
-    u16 const super_user_group_id{};
-    u32 const first_inode_id{};
-    u16 const inode_size{};
-    u16 const superblock_group_id{};
-    u32 const compatible_features{};
-    u32 const incompatible_features{};
-    u32 const read_only_compatible_features{};
-    u08_arr<16> const uuid{};
-    chr_arr<16> const volume_name{};
-    chr_arr<64> const last_mount_point{};
-    u32 const compression_algorithm{};
-    u08 const file_preallocated_blocks_count{};
-    u08 const directory_preallocated_blocks_count{};
-    u16 const _padding{};
-    u08_arr<16> const journal_superblock_uuid{};
-    u32 const journal_inode_id{};
-    u32 const journal_device_number{};
-    u32 const last_orphan_inode_id{};
-    u32_arr<4> const hash_seed{};
-    u08 const hash_version{};
-    u08_arr<3> const _reserved0{};
-    u32 const default_mount_options{};
-    u32 const first_meta_block_group_id{};
-    u08_arr<760> const _reserved1{};
+    u32 const inodes_count{}; ///< The total number of inodes in the file system
+    u32 const blocks_count{}; ///< The total number of blocks in the file system
+    u32 const reserved_blocks_count{}; ///< The number of blocks reserved for the super user
+    u32 const free_blocks_count{}; ///< The number of free blocks in the file system
+    u32 const free_inodes_count{}; ///< The mumber of free inodes in the file system
+    u32 const first_data_block_id{}; ///< The first block that carries user data in the file system
+    u32 const logical_block_size{}; ///< The logical size of a block (1024 << logical_block_size)
+    s32 const logical_fragment_size{}; ///< The logical size of a block (1024 << logical_fragment_size)
+    u32 const blocks_per_group{}; ///< The number of blocks per block group
+    u32 const fragments_per_group{}; ///< The number of fragments per block group
+    u32 const inodes_per_group{}; ///< The number of inodes per block group
+    u32 const last_mount_timestamp{}; ///< The unix timestamp when the file system was last mounted
+    u32 const last_write_timestamp{}; ///< The unix timestamp of the last write operation to the file system
+    u16 const mount_count{}; ///< The number of times the file system was mounted since the last check
+    u16 const maximum_mount_count{}; ///< The maximum number of times the file system can be mounted until a full check
+    u16 const magic_number{}; ///< The magic number identifying the file system type
+    s16 const state{}; ///< The state of the file system
+    s16 const error_behaviour{}; ///< The desired behaviour if a file system error occurs
+    s16 const revision_level_minor{}; ///< The minor revision level of the file system
+    u32 const last_check_timestamp{}; ///< The unix timestamp of the last check of the file system
+    u32 const check_interval{}; ///< The unix time interval in which to check the file system
+    u32 const creator_operating_system_id{}; ///< The operation system identifier of the OS that created the file system
+    u32 const revision_level{}; ///< The revision level of the file system
+    u16 const super_user_id{}; ///< The user ID of the super user
+    u16 const super_user_group_id{}; ///< The group ID of the super user group
+    u32 const first_inode_id{}; ///< The id of the first inode usable for standard files
+    u16 const inode_size{}; ///< The size of an inode in bytes
+    u16 const superblock_group_id{}; ///< The ID of the block group hosting this superblock
+    u32 const compatible_features{}; ///< The active compatible features
+    u32 const incompatible_features{}; ///< The active incompatible feature
+    u32 const read_only_compatible_features{}; ///< The active features compatible with read-only mode
+    u08_arr<16> const uuid{}; ///< The UUID of the file system
+    chr_arr<16> const label{}; ///< The label of the file system
+    chr_arr<64> const last_mount_point{}; ///< The location the file system was last mounted on
+    u32 const compression_algorithm{}; ///< The compression algorithm used in the file system
+    u08 const file_preallocated_blocks_count{}; ///< The number of blocks to preallocate for a file
+    u08 const directory_preallocated_blocks_count{}; ///< The number of block to preallocate for a directory
+    u16 const _padding{}; ///< Alignment padding
+    u08_arr<16> const journal_superblock_uuid{}; ///< The UUID of the superblock containing the journal
+    u32 const journal_inode_id{}; ///< The ID of the inode hosting the journal
+    u32 const journal_device_number{}; ///< The device number of the journal
+    u32 const last_orphan_inode_id{}; ///< The first inode in the list of inodes to delete
+    u32_arr<4> const hash_seed{}; ///< The seed for the directory hashing algorithm
+    u08 const hash_version{}; ///< The version of the directory hashing algorithm
+    u08_arr<3> const _reserved0{}; ///< Alignment padding
+    u32 const default_mount_options{}; ///< The default mount options for the file system
+    u32 const first_meta_block_group_id{}; ///< The ID of the first meta block group
+    u08_arr<760> const _reserved1{}; ///< Padding
     };
 
   static_assert(sizeof(extfs_superblock) == 1024, "An ext* super block must have an exact size of 1024 byte!");
diff --git a/include/fs/detail/types.hpp b/include/fs/detail/types.hpp
new file mode 100644
index 0000000..df84512
--- /dev/null
+++ b/include/fs/detail/types.hpp
@@ -0,0 +1,42 @@
+#ifndef EXTFS_TYPES_HPP
+#define EXTFS_TYPES_HPP
+
+#include <array>
+#include <cstdint>
+
+namespace fs::detail
+  {
+
+  using u32 = std::uint32_t; ///< An unsigned 32-bit integer
+  using s32 = std::int32_t; ///< A signed 32-bit integer
+  using u16 = std::uint16_t; ///< An unsigned 16-bit integer
+  using s16 = std::uint16_t; ///< A signed 16-bit integer
+  using u08 = std::uint8_t; ///< An unsigned 8-bit integer
+
+  /**
+   * An array of characters
+   *
+   * @tparam Size The size of the array
+   */
+  template<std::size_t Size>
+  using chr_arr = std::array<char, Size>;
+
+  /**
+   * An array of unsigned 8-bit integers
+   *
+   * @tparam Size The size of the array
+   */
+  template<std::size_t Size>
+  using u08_arr = std::array<u08, Size>;
+
+  /**
+   * An array of unsigned 32-bit integers
+   *
+   * @tparam Size The size of the array
+   */
+  template<std::size_t Size>
+  using u32_arr = std::array<u32, Size>;
+
+  }
+
+#endif