documenting layers and decks

Author: djowel

lib/include/elements/element/layer.hpp

@@ -11,9 +11,14 @@
 
 namespace cycfi::elements
 {
-   ////////////////////////////////////////////////////////////////////////////
-   // Layer
-   ////////////////////////////////////////////////////////////////////////////
+   /**
+    * @class layer_element
+    *
+    * @brief
+    *    A class which represents an element in a layer. The layer_element is
+    *    a composite that allows groups of elements to be placed in the
+    *    z-axis. Higher-level elements obscure or hide lower-level elements.
+    */
    class layer_element : public composite_base
    {
    public:
@@ -32,8 +37,29 @@ namespace cycfi::elements
       point                   _previous_size;
    };
 
+   /**
+    * @brief
+    *    `layer_composite` is a composite with indeterminate (dynamic)
+    *    number of elements
+    */
    using layer_composite = vector_composite<layer_element>;
 
+   /**
+    * @brief
+    *    Create a layer from provided elements. The layer contains group of
+    *    elements placed in z-axis. Higher-level elements obscure or hide
+    *    lower-level elements.
+    *
+    * @tparam E
+    *    Variadic template parameter for the types of the elements.
+    *
+    * @param elements
+    *    The elements to be added to the layer (a parameter pack).
+    *
+    * @return
+    *    A reverse layer composite of the provided elements (top-most element
+    *    last).
+    */
    template <typename... E>
    inline auto layer(E&&... elements)
    {
@@ -45,9 +71,14 @@ namespace cycfi::elements
       return r;
    }
 
-   ////////////////////////////////////////////////////////////////////////////
-   // Deck
-   ////////////////////////////////////////////////////////////////////////////
+   /**
+    * @class deck_element
+    *
+    * @brief
+    *    Represents an element in a deck, which inherits from the
+    *    `layer_element` class. Elements are placed in the z-axis. Unlike
+    *    layers, only the selected element is active (top-most by default).
+    */
    class deck_element : public layer_element
    {
    public:
@@ -72,8 +103,28 @@ namespace cycfi::elements
       std::size_t          _selected_index;
    };
 
+   /**
+    * @brief
+    *    `deck_composite` is a composite with indeterminate (dynamic)
+    *    number of elements
+    */
    using deck_composite = vector_composite<deck_element>;
 
+   /**
+    * @brief
+    *    Create a deck from provided elements. The deck contains a group of
+    *    elements placed in z-axis. Unlike layers, only the selected element
+    *    is active (top-most by default).
+    *
+    * @tparam E
+    *    Variadic template parameter for the types of the elements.
+    *
+    * @param elements
+    *    The elements to be added to the deck (a parameter pack).
+    *
+    * @return
+    *    A deck composite of the provided elements.
+    */
    template <typename... E>
    inline auto deck(E&&... elements)
    {