docs: improve formatting and document structure

Change-Id: I530d58f2700eb264855843021db32f568d373a1d
diff --git a/.waf-tools/default-compiler-flags.py b/.waf-tools/default-compiler-flags.py
index 4debb4e..3a7bf66 100644
--- a/.waf-tools/default-compiler-flags.py
+++ b/.waf-tools/default-compiler-flags.py
@@ -145,9 +145,9 @@
         flags = super(GccBasicFlags, self).getDebugFlags(conf)
         flags['CXXFLAGS'] += ['-Og',
                               '-g3',
-                              '-pedantic',
                               '-Wall',
                               '-Wextra',
+                              '-Wpedantic',
                               '-Werror',
                               '-Wcatch-value=2',
                               '-Wextra-semi',
@@ -163,9 +163,9 @@
         flags = super(GccBasicFlags, self).getOptimizedFlags(conf)
         flags['CXXFLAGS'] += ['-O2',
                               '-g',
-                              '-pedantic',
                               '-Wall',
                               '-Wextra',
+                              '-Wpedantic',
                               '-Wcatch-value=2',
                               '-Wextra-semi',
                               '-Wnon-virtual-dtor',