Reference documentation, guides, FAQ, hero subheading, and more (#240)

docs/docs/getting-started/dependency_installation/linux.md

@@ -1,4 +1,4 @@
-# Setting up Linux for Android Builds
+# Setting up Ubuntu Linux for Android Builds
 
 ## 1. Install Git, Python, CMake, OpenJDK, and qemu-kvm
 

docs/docs/getting-started/faq.md

@@ -0,0 +1,52 @@
+# FAQ
+
+## What platforms are supported?
+
+Currently Boden supports iOS and Android. Desktop platforms will be supported in the future, but we cannot nail down a date yet.
+
+## On which platforms can I develop apps based on Boden?
+
+On macOS, Linux, and Windows.
+
+To compile, run, and deploy iOS apps, you will need a Mac.
+
+## What IDEs are supported?
+
+Xcode on macOS, Android Studio on Linux and Windows.
+
+Other workflows are possible, but we don't advertise them actively as they have not yet been thoroughly tested.
+
+## How does licensing work?
+
+Boden is an open-source project currently licensed under the GNU General Public License. You can choose which version of the GPL you like better (2 or 3). Copy the respective Boden license file into your derivative project's repo and you're all set.
+
+In the future, we will most likely offer an LGPL licensing option as an alternative for those who find the GPL too restrictive.
+
+Finally, there will be a commercial licensing option for everyone who cannot or does not want to comply with the GPL.
+
+## Where can I get support?
+
+We recommend joining the [Boden Google Group](https://groups.google.com/forum/#!forum/boden-cross-platform-framework). We read every post in the group and will do our best to respond to questions quickly.
+
+## I found an issue. What should I do?
+
+Please open an issue on GitHub and tell us about it.
+
+## Can I already build a production app with Boden?
+
+Most likely not yet. But we're ramping up quickly, so this might change within the next weeks and months. We aim for a Boden 1.0 release by Q1/2020 and it will most likely be possible to create a producion app earlier.
+
+## Are desktop platforms supported?
+
+Not yet. But eventually they will be supported. See below.
+
+## Do you plan to support desktop platforms in the future?
+
+Yes. Most likely we will support macOS and Windows UWP in the future, but we don't yet know exactly when desktop support will land in Boden.
+
+Hint: There's unofficial macOS support already, but we don't talk about that as it's not going to be stable soon and is intended for internal testing purposes only at the moment.
+
+## Is Boden a Commercial Project?
+
+Yes. While Boden is free and open source, it is commercially developed by a full-time team. Our goal is to make sophisticated app development hassle-free for you and we believe there is no better way of ensuring the necessary resources are fully committed to the framework.
+

docs/docs/getting-started/first_app.md

@@ -1,6 +1,6 @@
-# Your first application
+# Your First Boden Application
 
-To create your first Boden project, open up a terminal (or command prompt), change to your local `boden` directory, and execute the following commands:
+To create your first Boden app, open up a terminal (or command prompt), change to your local `boden` directory, and execute the following commands:
 
 	python boden.py new -n AwesomeApp
 	cd AwesomeApp
@@ -12,7 +12,8 @@ In Xcode, select the `AwesomeApp` target and then press <kbd>Cmd</kbd>+<kbd>R</k
 
 In Android Studio, wait for Gradle to finish its sync and configuration processes and then select the `uidemo` target and press <kbd>Cmd</kbd>+<kbd>R</kbd> to build and run the example application, then select the `AwesomeApp` target and then press <kbd>Ctrl</kbd>+<kbd>R</kbd> on Mac or <kbd>Shift</kbd>+<kbd>F10</kbd> on Linux/Windows to build an run the Hello World application.
 
-> Note: On macOS and Linux you can also simply type `./boden` instead of calling `python boden.py` explicitly. If you want to build the Android version of the app on macOS, run `../boden open -p android`.
+!!! note
+    On macOS and Linux you can also simply type `./boden` instead of calling `python boden.py` explicitly. If you want to build the Android version of the app on macOS, run `../boden open -p android`.
 
 ## Hello World
 

docs/docs/getting-started/index.md

@@ -1,11 +1,36 @@
-You can use macOS to build both iOS and Android apps. Windows and Linux can be used to build Android apps only. This guide will help you set up your system for developing Boden apps.
+# Quickstart
 
-Which platform do you want to set up for development?
+## Prerequisites
 
-* [macOS](./setup/mac.md)
-* [Windows](./setup/win.md)
-* [Linux](./setup/linux.md)
+On a Mac: macOS 10.14+, [Xcode 10.1+](https://developer.apple.com/xcode/), [Python 3.4+](https://www.python.org/downloads/), [CMake 3.10.2+](https://cmake.org/download/).
 
+On Windows: Windows 10, [Python 3.4+](https://www.python.org/downloads/), [CMake 3.10.2+](https://cmake.org/download/), [Git](https://git-scm.com/download/win), [Oracle JDK 8](https://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html), and [Android Studio](https://developer.android.com/studio) (with Android NDK).
 
+On Ubuntu 18.04: `sudo apt update && sudo apt install git cmake python3-distutils openjdk-8-jdk qemu-kvm` plus [Android Studio](https://developer.android.com/studio/).
 
+## Step 1: Clone the Boden Repo
 
+	git clone --recurse-submodules https://github.com/AshampooSystems/boden.git
+
+## Step 2: Generate and Open an IDE Project
+
+	cd boden
+	python boden.py open
+
+This will bring up Xcode on macOS or Android Studio on Linux/Windows.
+
+If anything goes wrong, please make sure that all dependencies are installed and set up correctly. Check out our extended guides for help:
+
+* [Building on macOS](setup/mac)
+* [Building on Windows](setup/win)
+* [Building on Linux](setup/linux)
+
+## Step 3: Run a Boden Example Application
+
+In Xcode, select the `uidemo` target and hit <kbd>Cmd</kbd>+<kbd>R</kbd>.
+
+In Android Studio, select the `uidemo` target and hit <kbd>Shift</kbd>+<kbd>F10</kbd>.
+
+## Step 4: Create Your First Boden Application
+
+Still with us? Great! Now [learn how to create your first Boden application](first_app.md).

docs/docs/guides/index.md

@@ -1,3 +1 @@
-# Overview
-
-
+# Guides Overview

docs/docs/guides/ui/writing_view.md

@@ -471,9 +471,9 @@ namespace bdn::ios {
 ## Sending notifications to the View
 
 To allow the user to react the Button clicks we need a way to call functions of the View from the Core.
-For this we can use a combination of a [Notifier](../../reference/foundation/notifier.md) and a [WeakCallback](../../reference/foundation/weak_callback.md).
+For this we can use a combination of a [Notifier](../../reference/foundation/notifier.md) and a `WeakCallback`.
 
-First we add the [WeakCallback](../../reference/foundation/weak_callback.md) to our Core:
+First we add the `WeakCallback` to our Core:
 
 ```C++
 class ExampleButtonView : public View
@@ -634,7 +634,7 @@ class ExampleButtonView
 	}
 	```
 
-And at last we connect it to the [WeakCallback](../../reference/foundation/weak_callback.md):
+And at last we connect it to the `WeakCallback`:
 
 ```c++
 void ExampleButtonView::bindViewCore()

docs/docs/index.md

@@ -2,7 +2,7 @@ template: hero.html
 
 # Build real native mobile apps using modern C++17 and Boden
 
-With Boden you can write your mobile apps in modern C++17 and compile 100% native Android and iOS apps from the same statically typed codebase. No need for scripting, no overhead introduced by additional VMs.
+Write your mobile apps in modern C++17 and compile 100% native Android and iOS apps from the same statically typed codebase. No need for scripting. No overhead introduced by virtual machines. Using Boden is straight forward:
 
 ```C++
 // MainViewController.cpp

docs/docs/reference/foundation/application.md

@@ -3,7 +3,9 @@ source: Application.h
 
 # Application
 
-Represents the Application. Inherit from [ApplicationController](application_controller.md) to set up your application.
+Represents the Application.
+
+To define the setup and behavior of your own app, inherit from [ApplicationController](application_controller.md).
 
 The application's entry point is defined by the `BDN_APP_INIT` macro. See [ApplicationController](application_controller.md) for an example.
 
@@ -14,32 +16,41 @@ class Application
 	: public std::enable_shared_from_this<Application>
 ```
 
-## Macros
+## Obtaining the Global Application Instance
+
+* **static std::shared_ptr<Application\> globalApplication()**
+
+	Returns the global `Application` instance for the current process.
 
-* **BDN_APP_INIT(ClassName)**
+## Registering an Application Controller
 
-	Use this macro to register your main application controller
+* **BDN_APP_INIT(ApplicationControllerClassName)**
+
+	Use this macro to register your main application controller.
 
 ## Properties
 
 * **Property<std::vector<String\>\> commandLineArguments**
 
-	A list of the command-line arguments
+	A list of command-line arguments as specified when the application was launched.
 
 * **std::shared_ptr<[DispatchQueue](dispatch_queue.md)> dispatchQueue()**
 
-	The main thread [DispatchQueue](dispatch_queue.md)
+	The main thread's [`DispatchQueue`](dispatch_queue.md).
 
 * **std::shared_ptr<ApplicationController> applicationController()**
 
-	The user-supplied application controller
+	The user-defined application controller associated with the application.
 
 ## Commandline arguments
 
 * **int argc()**
+
+	Returns the number of command-line arguments.
+
 * **char \*\*argv()**
 
-	Returns the raw commandline arguments
+	Returns the raw command-line arguments.
 
 ## Main thread
 
@@ -59,12 +70,12 @@ class Application
 
 * **virtual void openURL(const String &url)**
 
-	Calls the operating system to open the supplied URL.
+	Opens the given URL in a suitable external application. Web URLs will be opened in the system's standard web browser. Application-specific URLs will open in the respective application.
 
 ## Shutdown
 
 * **void initiateExitIfPossible(int exitCode)** 
 
-	Tries to shutdown the application with the supplied exit code.
+	Tries to shutdown the application with the given exit code.
 
-	This function does nothing on mobile operating systems that do not allow the app to exit on its own.
+	Does nothing on Android.

docs/docs/reference/foundation/dispatch_queue.md

@@ -3,7 +3,7 @@ source: DispatchQueue.h
 
 # DispatchQueue
 
-A DispatchQueue can execute arbitrary functions on a thread.
+Queues and executes arbitrary functions on a thread.
 
 ## Declaration
 
@@ -17,42 +17,42 @@ class DispatchQueue
 * **using Clock = std::chrono::steady_clock**
 * **using TimePoint = Clock::time_point**
 
-## Constructor
+## Creating a DispatchQueue Object
 
 * **DispatchQueue(bool slave = false)**
 
-	If slave is `false`, create an internal thread for the DispatchQueue. 
+	Constructs a dispatch queue. If `slave` is `false` (the default), creates and manages a thread for the dispatch queue. If `slave` is `true`, the queue will not create a thread on its own. This is handy if there is already a thread/run loop which should be integrated with the dispatch queue.
 
-## Enqueue
+## Dispatching Methods to the Queue
 
 * **void dispatchSync([Function](#types) function)**
 
-	Dispatches a `function`on the DispatchQueue thread and waits for it to finish.
+	Dispatches a `function`on the dispatch queue thread and waits for it to finish.
 
 * **void dispatchAsync([Function](#types) function)**
 
-	Dispatches a `function` on the DispatchQueue thread.
+	Dispatches a `function` on the dispatch queue thread and returns immediately.
 
 * **template <\> void dispatchAsyncDelayed(std::chrono::duration<\> delay, [Function](#types) function)**
 
-	Dispatches a `function` to run on the DispatchQueue thread after the `delay`.
+	Dispatches a `function` to run on the dispatch queue thread after the `delay`.
 
-## Timer
+## Creating Timers
 
 * **template<\> createTimer(std::chrono::duration<\> interval, std::function<bool()\> timer)**
 
-	Creates a timer that will run `timer` repeatedly on the DispatchQueue's thread every `interval` until `timer` returns false.
+	Creates a timer that will run `timer` repeatedly on the dispatch queue's thread every `interval` until `timer` returns `false`.
 
-## Processing
+## Controlling the Queue's Internal Processing
 
 * **void enter()**
 
-	Only allowed if `slave` was true during construction. Starts the processing until `cancel` is called
+	Starts processing synchronously until `cancel` is called. Only allowed if `slave` was true during construction.
 
 * **void cancel()**
 
-	Stops processing
+	Stops processing as soon as possible.
 
 * **void executeSync()**
 
-	Execute a single item.
+	Executes the next function scheduled on the queue and returns.

docs/docs/reference/foundation/notifier.md

@@ -3,7 +3,7 @@ source: Notifier.h
 
 # Notifier
 
-Represents a signal used to notify observers of events and value changes.
+Notifies subscribing callback methods about an event synchronously.
 
 ## Declaration
 
@@ -16,37 +16,37 @@ class Notifier
 
 * **using Subscription = size_t**
 
-	An ID referencing a specific subscription
+	An ID referencing a specific subscription.
 
 * **using Target = std::function<void(Arguments...)\>**
 
-	The type of a callback
+	The type of a callback.
 
-## Subscribe
+## Subscribing to a Notifier
 
 * **Subscription subscribe(Target target)**
 
-	Adds a new subscription
+	Subscribes the function specified by `target` to the notifier and returns a `Subscription` value. The returned `Subscription` may be persisted by the caller to later unsubscribe from the subscription again.
 
 * **Notifier<Arguments...\> operator+=(Target target)**
 
-	Convenience function to add a new subscription
+	Convenience for adding a new subscription by using `operator +=`. If you need to unsubscribe the subscriber later on, use `subscribe` instead.
 
-## Unsubscribe
+## Unsubscribing from a Notifier
 
 * **void unsubscribe(Subscription subscription)**
 	
-	Unsubscribe a specific subscription
+	Unsubscribe the given subscription.
 
 * **void unsubscribeAll()**
 
-	Removes all subscriptions
+	Unsubscribe all subscriptions.
 
 !!! note
-	It is safe and valid to unsubscribe during a notify() call
+	It is safe to unsubscribe during a notify() call
 
-## Notify
+## Notifying Subscribers
 
 * **void notify(*Arguments*... arguments)**
 
-	Notifies all registered subscriptions
+	Notifies all subscribers. Passes the given arguments to each subscriber.