KDAB · ahayzen-kdab · Sep 12, 2023 · Sep 13, 2023 · Sep 22, 2023 · Oct 10, 2023
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -25,6 +25,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Ability to define a custom C++ Constructor using `cxx_qt::Constructor`
 - `cxx_qt::Initialize` trait for easier default-constructor implementation
 - `extern "C++Qt"` block support for declaring existing types with methods and signals
+- `#[qenum]` attribute for `Q_ENUM` and `Q_ENUM_NS` support
+- `qnamespace!` macro to support exposing namespaced enums to QML
 
 ### Changed
 

diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md
@@ -7,28 +7,28 @@ SPDX-License-Identifier: MIT OR Apache-2.0
 
 # Summary
 
-[Introduction](./index.md)
-
----
-
+- [Introduction](./index.md)
 - [Getting Started](./getting-started/index.md)
     - [QObjects in Rust](./getting-started/1-qobjects-in-rust.md)
     - [Our first CXX-Qt module](./getting-started/2-our-first-cxx-qt-module.md)
     - [Creating the QML GUI](./getting-started/3-qml-gui.md)
     - [Building with CMake](./getting-started/4-cmake-integration.md)
     - [Building with Cargo](./getting-started/5-cargo-executable.md)
-- [QObject](./qobject/index.md)
-    - [`#[cxx_qt::bridge]` - Bridge Macro](./qobject/bridge-macro.md)
-    - [`#[qobject]` - Defining QObjects](./qobject/qobject_struct.md)
-    - [`#[qsignal]` - Signal macro](./qobject/signals.md)
-    - [`qobject::T` - The generated QObject](./qobject/generated-qobject.md)
-    - [CxxQtThread](./qobject/cxxqtthread.md)
-- [Concepts](./concepts/index.md)
-    - [Bridge](./concepts/bridge.md)
-    - [Qt](./concepts/qt.md)
-    - [Types](./concepts/types.md)
+- [Core Concepts](./concepts/index.md)
     - [Build Systems](./concepts/build_systems.md)
-    - [Threading](./concepts/threading.md)
-    - [Nested Objects](./concepts/nested_objects.md)
-    - [Inheritance & Overriding](./concepts/inheritance.md)
-    - [Custom Constructors](./concepts/constructor.md)
+    - [Generated QObject](./concepts/generated_qobject.md)
+    - [Types](./concepts/types.md)
+- [Reference: the bridge module](./bridge/index.md)
+    - [extern "RustQt"](./bridge/extern_rustqt.md)
+    - [extern "C++Qt"](./bridge/extern_cppqt.md)
+    - [Shared types](./bridge/shared_types.md)
+    - [Attributes](./bridge/attributes.md)
+- [Reference: traits](./traits/index.md)
+    - [CxxQtType](./traits/cxxqttype.md)
+    - [Constructor](./traits/constructor.md)
+    - [Initialize](./traits/initialize.md)
+    - [Locking](./traits/locking.md)
+    - [Threading](./traits/threading.md)
+- [Advanced Topics](./advanced/index.md)
+    - [Nested Objects](./advanced/nested_objects.md)
+    - [Inheritance & Overriding](./advanced/inheritance.md)
diff --git a/book/src/advanced/index.md b/book/src/advanced/index.md
@@ -0,0 +1,11 @@
+<!--
+SPDX-FileCopyrightText: 2023 Klarälvdalens Datakonsult AB, a KDAB Group company <info@kdab.com>
+SPDX-FileContributor: Andrew Hayzen <andrew.hayzen@kdab.com>
+
+SPDX-License-Identifier: MIT OR Apache-2.0
+-->
+
+# Advanced Topics
+
+  * [Nesting Rust objects](./nested_objects.md)
+  * [Inheriting QObjects and overriding methods](./inheritance.md)
diff --git a/book/src/concepts/inheritance.md → book/src/advanced/inheritance.md b/book/src/concepts/inheritance.md → book/src/advanced/inheritance.md
@@ -7,12 +7,16 @@ SPDX-License-Identifier: MIT OR Apache-2.0
 
 # Inheritance
 
+<!--
+TODO: check and rewrite
+-->
+
 Some Qt APIs require you to override certain methods from an abstract base class, for example [QAbstractItemModel](https://doc.qt.io/qt-6/qabstractitemmodel.html).
 
 To support creating such subclasses directly from within Rust, CXX-Qt provides you with multiple helpers.
 
 Some superclasses may require special parameters for construction.
-This can be achieved by using a [custom constructor](./constructor.md).
+This can be achieved by using a [custom constructor](../traits/constructor.md).
 
 ## Accessing base class methods
 To access the methods of a base class in Rust, use the `#[inherit]` macro.

diff --git a/book/src/concepts/nested_objects.md → book/src/advanced/nested_objects.md b/book/src/concepts/nested_objects.md → book/src/advanced/nested_objects.md
@@ -7,6 +7,10 @@ SPDX-License-Identifier: MIT OR Apache-2.0
 
 # Nested Objects
 
+<!--
+TODO: check and rewrite
+-->
+
 Rust Qt objects can be nested as properties or parameters of each other.
 
 A nested object is referred to by using a pointer to its QObject representation.

diff --git a/book/src/bridge/attributes.md b/book/src/bridge/attributes.md
@@ -0,0 +1,47 @@
+<!--
+SPDX-FileCopyrightText: 2023 Klarälvdalens Datakonsult AB, a KDAB Group company <info@kdab.com>
+SPDX-FileContributor: Andrew Hayzen <andrew.hayzen@kdab.com>
+
+SPDX-License-Identifier: MIT OR Apache-2.0
+-->
+
+# Attributes
+
+## namespace
+
+The C++ namespace which to emit `extern "RustQt"` items and the namespace to find `extern "C++Qt"` items.
+
+An item will inherit the namespace specified on it's surrounding `extern` block if any,
+otherwise the namespace specified with the top level `cxx_qt::bridge` attribute, if any, will be used.
+
+```rust,ignore,noplayground
+{{#include ../../../examples/qml_features/rust/src/threading.rs:book_namespace_macro}}
+```
+
+> Note that `#[namespace = "..."]` may not work on all items,
+> we hope to improve this in future this support in the future.
+
+## cxx_name and rust_name
+
+The `#[cxx_name = "..."]` attribute replaces the name that C++ should use for this item.
+
+The `#[rust_name = "..."]` attribute replaces the name that Rust should use for this item.
+
+> Note that `#[cxx_name = "..."]` and `#[rust_name = "..."]` may not work on all items,
+> we hope to improve this in future this support in the future.
+
+If no `#[cxx_name = "..."]` or `#[rust_name = "..."]` is specified, CXX-Qt will perform an automatic conversion to function names as specified in the table below.
+
+|                  | Rust       | C++       |
+|------------------|------------|-----------|
+| `extern "C++Qt"` | -          | camelCase |
+| `extern "RustQt"`| -          | camelCase |
+
+> Note that in some cases `snake_case` conversions may occur for generated functions in Rust (eg `on_<signal>`).
+
+> Note that this table may change to the following conversions in the future.
+>
+> |                  | Rust       | C++       |
+> |------------------|------------|-----------|
+> | `extern "C++Qt"` | snake_case | -         |
+> | `extern "RustQt"`| -          | camelCase |
diff --git a/book/src/bridge/extern_cppqt.md b/book/src/bridge/extern_cppqt.md
@@ -0,0 +1,104 @@
+<!--
+SPDX-FileCopyrightText: 2023 Klarälvdalens Datakonsult AB, a KDAB Group company <info@kdab.com>
+SPDX-FileContributor: Andrew Hayzen <andrew.hayzen@kdab.com>
+
+SPDX-License-Identifier: MIT OR Apache-2.0
+-->
+
+# extern "C++Qt"
+
+- [QObjects](#qobjects)
+- [Methods](#methods)
+- [Signals](#signals)
+
+```rust,ignore,noplayground
+#[cxx_qt::bridge]
+mod ffi {
+    extern "C++Qt" {
+
+    }
+}
+```
+
+The `extern "C++Qt"` section of a CXX-Qt bridge declares Qt types and signatures to be made available to Rust,
+and gives the paths of the headers which contain the corresponding Qt declarations.
+
+A bridge module may contain zero or more `extern "C++Qt"` blocks.
+
+This complements the [`extern "C++"` CXX section](https://cxx.rs/extern-c++.html)
+but allows for declaring Qt specific features on C++ types.
+
+## QObjects
+
+Types defined in C++ that are made available to Rust, but only behind an indirection.
+
+This is the same as [CXX Opaque C++ types](https://cxx.rs/extern-c++.html#opaque-c-types).
+
+```rust,ignore,noplayground
+#[cxx_qt::bridge]
+mod ffi {
+    extern "C++Qt" {
+        include!(<QtWidgets/QPushButton>);
+        type QPushButton;
+    }
+}
+```
+
+<!--
+TODO: use a real example from qml_features once closure support lands
+-->
+
+## Methods
+
+Methods can be specified on the Qt type in the same way as [`extern "RustQt"` blocks](./extern_rustqt.md#methods).
+
+This is the same as [CXX Functions and member functions](https://cxx.rs/extern-c++.html#functions-and-member-functions).
+
+```rust,ignore,noplayground
+#[cxx_qt::bridge]
+mod ffi {
+    unsafe extern "C++" {
+        include!("cxx-qt-lib/qstring.h");
+        type QString = cxx_qt_lib::QString;
+    }
+
+    extern "C++Qt" {
+        include!(<QtWidgets/QPushButton>);
+        type QPushButton;
+
+        fn text(self: &QPushButton) -> QString;
+        fn setText(self: Pin<&mut QPushButton>, text: &QString);
+    }
+}
+```
+
+<!--
+TODO: use a real example from qml_features once closure support lands
+-->
+
+## Signals
+
+Signals can be specified on the Qt type in the same way as [`extern "RustQt"` blocks](./extern_rustqt.md#signals).
+
+```rust,ignore,noplayground
+#[cxx_qt::bridge]
+mod ffi {
+    extern "C++Qt" {
+        include!(<QtWidgets/QPushButton>);
+        type QPushButton;
+
+        #[qsignal]
+        fn clicked(self: Pin<&mut QPushButton>, checked: bool);
+    }
+}
+```
+
+This then causes CXX-Qt to generate Rust methods to connect to the `#[qsignal]` with a closure,
+in the same way as a `#[qsignal]` in a [`extern "RustQt"` block](./extern_rustqt.md#signals).
+
+> Note using `pub(self)` as the visibility of the signal
+> allows for declaring private signals
+
+<!--
+TODO: use a real example from qml_features once closure support lands
+-->