C++ docs: First draft of a sixtyfps namespace intro

api/sixtyfps-cpp/include/sixtyfps.h

@@ -30,6 +30,32 @@ struct ItemVTable;
 #include "sixtyfps_backend_internal.h"
 #include "sixtyfps_qt_internal.h"
 
+/// \rst
+/// The :code:`sixtyfps` namespace is the primary entry point into the SixtyFPS C++ API.
+/// All available types are in this namespace.
+///
+/// There are two ways of loading :code:`.60` markup files in your application:
+///
+/// #. You could translate them to C++ with the help of the :code:`sixtyfps_target_60_sources`
+///    cmake command and use the generated C++ API to instantiate the UI, set or get property
+///    values or callback handlers. That API will use types from the :code:`sixtyfps` namespace,
+///    for example :cpp:class:`sixtyfps::SharedString` or :cpp:class:`sixtyfps::Color`.
+/// #. Alternatively, you can choose to load the :code:`.60` files dynamically at run-time, using
+///    the SixtyFPS Interpreter from the :code:`sixtyfps::interpreter` namespace, starting at
+///    :cpp:class:`sixtyfps::interpreter::ComponentCompiler`.
+///
+/// Once you have loaded or instantiated a `.60` file, you will receive a reference to the instance
+/// in a :cpp:class:`sixtyfps::ComponentHandle`. This is a smart pointer that owns
+/// the actual instance and keeps it alive as long as at least one
+/// :cpp:class:`sixtyfps::ComponentHandle` is in scope, similar to :code:`std::shared_ptr<T>`.
+///
+/// For more complex UIs it is common to supply data in the form of an abstract data model, that is
+/// used with :code:`for` - :code:`in` repetitions or :code:`ListView` elements in the :code:`.60`
+/// language. All models in C++ are sub-classes of the :cpp:class:`sixtyfps::Model` and you can
+/// sub-class it yourself. For convenience, the :cpp:class:`sixtyfps::VectorModel` provides an
+/// implementation that is backed by a :code:`std::vector<T>`.
+///
+/// \endrst
 namespace sixtyfps {
 
 // Bring opaque structure in scope
@@ -322,7 +348,8 @@ using ModelPeer = std::weak_ptr<AbstractRepeaterView>;
 
 } // namespace private_api
 
-/// A Model is providing Data for the Repeater or ListView elements of the `.60` language
+/// A Model is providing Data for :code:`for` - :code:`in` repetitions or ListView elements of the
+/// `.60` language
 template<typename ModelData>
 class Model
 {