Update <libmaple/libmaple_types.h> page.

Signed-off-by: Marti Bolivar <mbolivar@leaflabs.com>

1 files changed, 55 insertions, 13 deletions

diff --git a/source/libmaple/api/libmaple_types.rst b/source/libmaple/api/libmaple_types.rst
index 7fed5dc..5ca446e 100644
--- a/source/libmaple/api/libmaple_types.rst
+++ b/source/libmaple/api/libmaple_types.rst
@@ -1,12 +1,15 @@
 .. highlight:: c
 .. _libmaple-libmaple_types:
 
-``libmaple_types.h``
-====================
+``<libmaple/libmaple_types.h>``
+===============================
 
 Defines the base types and type-related macros used throughout the
 rest of libmaple.
 
+.. contents:: Contents
+   :local:
+
 Integral Types
 --------------
 
@@ -22,22 +25,61 @@ Integral Types
 Attributes and Type Qualifiers
 ------------------------------
 
+In the case of macros for GCC's ``__attribute__``\ s, we have our own
+macros mostly to save typing, but also in hopes that they might be
+expressible using different compiler extensions, or to give them
+different interpretations when running e.g. Doxygen on libmaple.
+
+.. c:macro:: __always_inline
+
+   Macro for ``inline __attribute__((always_inline))``. This can be
+   used to defeat GCC's ``-Os`` when you Really Mean Inline.
+
+.. c:macro:: __attr_flash
+
+   Macro for a GCC ``__attribute__`` which (when using libmaple's
+   linker scripts) will cause the variable being marked to be stored
+   in Flash, rather than SRAM. It's useful for read-only variables
+   like look-up tables.
+
+.. c:macro:: __deprecated
+
+   Macro for ``__attribute__((deprecated))``. Its use causes GCC to
+   emit deprecation warnings when the deprecated functionality is
+   used. It's not used for everything that gets deprecated, so don't
+   rely on it to catch all uses of deprecated APIs.
+
+.. c:macro:: __packed
+
+   Macro for ``__attribute__((packed))``.
+
 .. c:macro:: __io
 
-   This is a macro for ``volatile`` which is used to denote that the
-   variable whose type is being qualified is IO-mapped.  Its most
-   common use is in the individual members of each :ref:`register map
+   Macro for ``volatile`` which denotes that the variable whose type
+   is being qualified is IO-mapped.  Its most common use is in the
+   individual members of each :ref:`register map
    <libmaple-overview-regmaps>` struct.
 
-.. c:macro:: __attr_flash
+.. c:macro:: __weak
 
-   This is a macro for a GCC ``__attribute__`` which (when using the
-   linker scripts provided with libmaple) will cause the variable
-   being marked to be stored in Flash, rather than SRAM.  The
-   variable's value may be read like that of any other variable, but
-   it may not be written.
+   Macro for ``__attribute__((weak))``.
 
-Other typedefs
---------------
+.. c:macro:: __unused
+
+   Macro for ``__attribute__((unused))``. This can be used
+   (sparingly!) to silence unused function warnings when GCC is
+   mistaken.
+
+Miscellaneous
+-------------
 
 .. doxygentypedef:: voidFuncPtr
+
+.. c:macro:: offsetof(type, member)
+
+   If left undefined, this is defined to ``__builtin_ofsetof(type,
+   member)``.
+
+.. c:macro:: NULL
+
+   If left undefined, this is defined to ``0``.