Add placeholders for documentation of new modules

arximboldi · May 12, 2020 · 46755ba · 46755ba
1 parent 88d33a0
commit 46755ba
Show file tree

Hide file tree

Showing 23 changed files with 196 additions and 51 deletions.
diff --git a/README.rst b/README.rst
@@ -32,9 +32,12 @@ via pure functions.  And you get time-travel for free!
 
 * **Documentation** (Contents_)
 * **Code** (GitHub_)
+* **CppRussia-Piter 2019 Talk**: *Squaring the circle* (`YouTube
+  <https://www.youtube.com/watch?v=e2-FRFEx8CA>`_, `Slides
+  <https://sinusoid.es/talks/cpprussia19-piter>`_)
 * **CppCon 2018 Talk**: *The most valuable values* (`YouTube
   <https://www.youtube.com/watch?v=_oBx_NbLghY>`_, `Slides
-  <https://public.sinusoid.es/talks/cppcon18>`_)
+  <https://sinusoid.es/talks/cppcon18>`_)
 * **C++ on Sea 2019 Talk**: *Postmodern immutable data-structures*
   (`YouTube <https://www.youtube.com/watch?v=y_m0ce1rzRI>`_, `Slides
   <https://sinusoid.es/talks/cpponsea19>`_)
@@ -116,29 +119,24 @@ This library is written in **C++17** and a compliant compiler and
 standard library necessary.  It is `continuously tested`_ with GCC 7,
 but it might work with other compilers and versions.
 
-It also depends on `Boost Hana`_. Some optional extensions and modules
+It also depends on `Zug`_ and `Boost Hana`_. Some optional extensions and modules
 may have other dependencies documented in their respective sections.
 
+.. _Zug: https://github.com/arximboldi/zug/
 .. _Boost Hana: https://boostorg.github.io/hana
 .. _continuously tested: https://travis-ci.org/arximboldi/immer
 
 Usage
 -----
 
-This is a **header only** library but to be configured correctly you need
-to run `CMake`_ first::
-
-    mkdir -p build && cd build
-    cmake .. -D lager_BUILD_DEBUGGER=OFF -D lager_BUILD_TESTS=OFF -D lager_BUILD_EXAMPLES=OFF -D lager_BUILD_DOCS=OFF
-
-Now you can just copy the ``lager``
-subfolder somewhere in your *include path*.
+This is a **header only** you can just copy the ``lager`` subfolder
+somewhere in your *include path*.
 
 Some components, like the time-travelling debugger, also require the
 installation of extra files.
 
-You can use `CMake`_ to install the library in your
-system once you have manually cloned the repository::
+You can use `CMake`_ to install the library in your system once you
+have manually cloned the repository::
 
     mkdir -p build && cd build
     cmake .. && sudo make install

diff --git a/doc/cursor.rst b/doc/cursor.rst
@@ -0,0 +1,7 @@
+
+cursor
+======
+
+.. doxygengroup:: cursors
+   :project: lager
+   :content-only:
diff --git a/doc/cursors.rst b/doc/cursors.rst
@@ -1,10 +1,18 @@
-
 .. _cursors:
 
 Cursors
 =======
 
-.. admonition:: TODO
+.. admonition:: Work in progress
    :class: danger
 
    This section of the documentation has not been written yet.
+
+   Meanwhile, you can watch the **C++ Russia 2019 Talk**: `Squaring
+   the circle: value oriented design in an object oriented system
+   <https://www.youtube.com/watch?v=e2-FRFEx8CA>`_ (`slides`_).
+
+.. _slides: https://sinusoid.es/talks/cpprussia19-piter
+
+.. image:: http://orvex.org.p11.hostingprod.com/images/under_construction.gif
+   :align: center
diff --git a/doc/doxygen.config b/doc/doxygen.config
@@ -8,6 +8,7 @@ GENERATE_XML     = YES
 INPUT            = \
                  ../lager \
                  ../lager/event_loop \
+                 ../lager/lenses \
                  ../lager/debug
 INCLUDE_PATH     = ..
 QUIET            = YES

diff --git a/doc/event_loop.rst b/doc/event_loop.rst
@@ -25,3 +25,14 @@ sdl
 
 .. doxygenstruct:: lager::sdl_event_loop
 .. doxygenstruct:: lager::with_sdl_event_loop
+
+qt
+----
+
+.. doxygenstruct:: lager::with_qt_event_loop
+
+qml
+----
+
+.. doxygenclass:: lager::event_loop_quick_item
+.. doxygenstruct:: lager::with_qml_event_loop
diff --git a/doc/index.rst b/doc/index.rst
@@ -17,16 +17,20 @@ Contents
    effects
    views
    modularity
+   cursors
+   lenses
    time-travel
 
 .. toctree::
    :caption: Reference
    :maxdepth: 3
 
    context
+   cursor
    debug
    deps
    event_loop
+   lens
    store
    util
 

diff --git a/doc/lens.rst b/doc/lens.rst
@@ -0,0 +1,11 @@
+
+lens
+====
+
+.. doxygengroup:: lenses-api
+   :project: lager
+   :content-only:
+
+.. doxygengroup:: lenses
+   :project: lager
+   :content-only:
diff --git a/doc/lenses.rst b/doc/lenses.rst
@@ -0,0 +1,18 @@
+.. _lenses:
+
+Lenses
+======
+
+.. admonition:: Work in progress
+   :class: danger
+
+   This section of the documentation has not been written yet.
+
+   Meanwhile, you can watch the **C++ Russia 2019 Talk**: `Squaring
+   the circle: value oriented design in an object oriented system
+   <https://www.youtube.com/watch?v=e2-FRFEx8CA>`_ (`slides`_).
+
+.. _slides: https://sinusoid.es/talks/cpprussia19-piter
+
+.. image:: http://orvex.org.p11.hostingprod.com/images/under_construction.gif
+   :align: center
diff --git a/doc/views.rst b/doc/views.rst
@@ -124,12 +124,10 @@ with a widget tree UI, by breaking the circle as follows:
 .. admonition:: Library support
 
    This diffing mechanism can be a bit cumbersome, and sometimes error
-   prone. At `Sinusoidal Engineering`_ we are developing a new library
-   to aid this particular use-case.  It will be first presented at the
-   `C++ Russia Piter`_ and `Meeting C++`_ conferences in Autumn 2019.
-
-.. _C++ Russia Piter: https://cppconf-piter.ru/en/
-.. _Meeting C++: http://meetingcpp.com/
+   prone. :ref:`cursors` can do it for you automatically.  They can
+   also do much more, and are an invaluable tool when `interfacing a
+   value-oriented data model with an object-oriented
+   UI<https://www.youtube.com/watch?v=e2-FRFEx8CA>`.
 
 Observables
 -----------

diff --git a/lager/constant.hpp b/lager/constant.hpp
@@ -38,6 +38,9 @@ auto make_constant_node(T&& v)
 
 } // namespace detail
 
+//! @defgroup cursors
+//! @{
+
 template <typename T>
 class constant : public reader_base<detail::constant_node<T>>
 {
@@ -61,4 +64,6 @@ auto make_constant(T&& v) -> constant<std::decay_t<T>>
     return std::forward<T>(v);
 }
 
+//! @}
+
 } // namespace lager
diff --git a/lager/cursor.hpp b/lager/cursor.hpp
@@ -22,6 +22,9 @@
 
 namespace lager {
 
+//! @defgroup cursors
+//! @{
+
 template <typename DerivT>
 struct cursor_mixin
     : writer_mixin<DerivT>
@@ -64,8 +67,6 @@ class cursor_base
 
 /*!
  * Provides access to reading and writing values of type `T`.
- * Model of `cursor_value`.
- * @see `cursor_value`
  */
 template <typename T>
 class cursor : public cursor_base<detail::cursor_node<T>>
@@ -76,4 +77,6 @@ class cursor : public cursor_base<detail::cursor_node<T>>
     using base_t::base_t;
 };
 
+//! @}
+
 } // namespace lager
diff --git a/lager/lens.hpp b/lager/lens.hpp
@@ -9,29 +9,38 @@ namespace lager {
 namespace detail {
 
 template <typename Whole, typename Part>
-struct lens_i {
+struct lens_i
+{
     virtual Part view(Whole const&) const              = 0;
     virtual Whole set(Whole const&, Part const&) const = 0;
 };
 
 template <typename Lens, typename Whole, typename Part>
-struct lens_holder : public lens_i<Whole, Part> {
+struct lens_holder : public lens_i<Whole, Part>
+{
     Lens value;
 
     template <typename T>
-    lens_holder(T&& other) : value{std::forward<T>(other)} {}
+    lens_holder(T&& other)
+        : value{std::forward<T>(other)}
+    {}
 
     Part view(Whole const& w) const override { return ::lager::view(value, w); }
 
-    Whole set(Whole const& w, Part const& p) const override {
+    Whole set(Whole const& w, Part const& p) const override
+    {
         return ::lager::set(value, w, p);
     }
 };
 
 } // namespace detail
 
+//! @defgroup lenses-api
+//! @{
+
 template <typename Whole, typename Part>
-class lens : zug::detail::pipeable {
+class lens : zug::detail::pipeable
+{
     std::shared_ptr<detail::lens_i<Whole, Part> const> holder_;
 
 public:
@@ -41,18 +50,22 @@ class lens : zug::detail::pipeable {
                   int>::type = 0>
     lens(Lens&& lens)
         : holder_{new detail::lens_holder<std::decay_t<Lens>, Whole, Part>{
-              std::forward<Lens>(lens)}} {}
+              std::forward<Lens>(lens)}}
+    {}
 
     template <typename F>
-    auto operator()(F &&f) const {
+    auto operator()(F&& f) const
+    {
         return [this, f = std::forward<F>(f)](auto&& p) {
             return f(holder_->view(std::forward<decltype(p)>(p)))(
                 [&](auto&& x) {
                     return holder_->set(std::forward<decltype(p)>(p),
-                                     std::forward<decltype(x)>(x));
+                                        std::forward<decltype(x)>(x));
                 });
         };
     }
 };
 
+//! @}
+
 } // namespace lager
diff --git a/lager/lenses.hpp b/lager/lenses.hpp
@@ -12,8 +12,8 @@
 
 #pragma once
 
-#include <zug/compose.hpp>
 #include <lager/util.hpp>
+#include <zug/compose.hpp>
 
 #include <type_traits>
 #include <utility>
@@ -25,16 +25,19 @@ template <typename T>
 struct const_functor;
 
 template <typename T>
-auto make_const_functor(T&& x) -> const_functor<T> {
+auto make_const_functor(T&& x) -> const_functor<T>
+{
     return {std::forward<T>(x)};
 }
 
 template <typename T>
-struct const_functor {
+struct const_functor
+{
     T value;
 
     template <typename Fn>
-    const_functor operator()(Fn&&) && {
+    const_functor operator()(Fn&&) &&
+    {
         return std::move(*this);
     }
 };
@@ -43,22 +46,28 @@ template <typename T>
 struct identity_functor;
 
 template <typename T>
-auto make_identity_functor(T&& x) -> identity_functor<T> {
+auto make_identity_functor(T&& x) -> identity_functor<T>
+{
     return {std::forward<T>(x)};
 }
 
 template <typename T>
-struct identity_functor {
+struct identity_functor
+{
     T value;
 
     template <typename Fn>
-    auto operator()(Fn&& f) && {
+    auto operator()(Fn&& f) &&
+    {
         return make_identity_functor(
             std::forward<Fn>(f)(std::forward<T>(value)));
     }
 };
 } // namespace detail
 
+//! @defgroup lenses-api
+//! @{
+
 template <typename LensT, typename T>
 decltype(auto) view(LensT&& lens, T&& x)
 {
@@ -86,8 +95,13 @@ decltype(auto) over(LensT&& lens, T&& x, Fn&& fn)
         .value;
 }
 
+//! @}
+
 namespace lenses {
 
+//! @defgroup lenses
+//! @{
+
 template <typename Getter, typename Setter>
 auto getset(Getter&& getter, Setter&& setter)
 {
@@ -103,4 +117,6 @@ auto getset(Getter&& getter, Setter&& setter)
 
 } // namespace lenses
 
+//! @}
+
 } // namespace lager
diff --git a/lager/lenses/at.hpp b/lager/lenses/at.hpp
@@ -55,6 +55,9 @@ std::decay_t<Whole> at_setter_impl(Whole&& whole, Part&& part, Key&& key)
 
 } // namespace detail
 
+//! @defgroup lenses
+//! @{
+
 /*!
  * `Key -> Lens<{X}, [X]>`
  */
@@ -78,5 +81,7 @@ auto at(Key key)
     });
 }
 
+//! @}
+
 } // namespace lenses
 } // namespace lager