From df90c7967be7d63c9e9d7d17d506486ed4c79be9 Mon Sep 17 00:00:00 2001 From: Daniil Korostelev Date: Wed, 19 Jun 2024 13:21:12 +0200 Subject: [PATCH] more docs love --- docs/articles/auto-async.md | 2 +- docs/articles/auto-run.md | 2 +- docs/articles/auto.md | 2 +- docs/articles/binding-batching.md | 2 +- docs/articles/binding.md | 2 +- docs/articles/collections-dict.md | 2 +- docs/articles/collections-list.md | 2 +- docs/articles/collections.md | 2 +- docs/articles/comparers.md | 2 +- docs/articles/const.md | 2 +- docs/articles/godot.md | 2 +- docs/articles/intro.md | 17 ----------------- docs/articles/observable.md | 4 ++-- docs/articles/{best-practices.md => remarks.md} | 3 ++- docs/articles/state.md | 2 +- docs/articles/toc.yml | 4 ++-- docs/articles/unity-lifetime-helper.md | 4 ++-- docs/articles/unity.md | 2 +- docs/index.md | 6 +++--- 19 files changed, 24 insertions(+), 40 deletions(-) delete mode 100644 docs/articles/intro.md rename docs/articles/{best-practices.md => remarks.md} (93%) diff --git a/docs/articles/auto-async.md b/docs/articles/auto-async.md index 45fc6a6..039532b 100644 --- a/docs/articles/auto-async.md +++ b/docs/articles/auto-async.md @@ -1,4 +1,4 @@ -## Asynchronous Auto-Observable +# Asynchronous Auto-Observable In addition to normal [`auto-observables`](auto.md), it is also possible to create auto-observables using `async` computation functions. Auto-observable will take care of starting and awaiting asynchronous computation while tracking observable access at their every execution step. diff --git a/docs/articles/auto-run.md b/docs/articles/auto-run.md index df39eaf..3237ec4 100644 --- a/docs/articles/auto-run.md +++ b/docs/articles/auto-run.md @@ -1,4 +1,4 @@ -## Auto-Runs +# Auto-Runs Sometimes we simply want to run some code that depends on observable values and have it automatically re-invoked in case any of the used values is changed. We could use an [auto-observable](auto.md) with some dummy value for that, however if there's no need for an actual value it can get a bit awkward. diff --git a/docs/articles/auto.md b/docs/articles/auto.md index 487037a..4e0e702 100644 --- a/docs/articles/auto.md +++ b/docs/articles/auto.md @@ -1,4 +1,4 @@ -## Auto-Observable +# Auto-Observable Auto-observables are the main way to derive observable data from a number of *source* observables by providing a *computation* function. diff --git a/docs/articles/binding-batching.md b/docs/articles/binding-batching.md index dadd33f..2b623dc 100644 --- a/docs/articles/binding-batching.md +++ b/docs/articles/binding-batching.md @@ -1,4 +1,4 @@ -## Binding batching +# Binding batching The binding mechanism is designed to support *batching*. This means that the binding callbacks are not executed directly when an observable value is changed, instead they are scheduled for execution all together in a batch once per *frame*. diff --git a/docs/articles/binding.md b/docs/articles/binding.md index 75acb93..0961742 100644 --- a/docs/articles/binding.md +++ b/docs/articles/binding.md @@ -1,4 +1,4 @@ -## Bindings +# Bindings We briefly mentioned the `Bind` method in the [`Observable`](observable.md) article, which allows for subscribing to `Observable` value changes to bind your code to it. diff --git a/docs/articles/collections-dict.md b/docs/articles/collections-dict.md index 33926ea..028bc69 100644 --- a/docs/articles/collections-dict.md +++ b/docs/articles/collections-dict.md @@ -1,3 +1,3 @@ -## Observable Dictionary +# Observable Dictionary > TODO: document diff --git a/docs/articles/collections-list.md b/docs/articles/collections-list.md index cbf2975..cd49f0a 100644 --- a/docs/articles/collections-list.md +++ b/docs/articles/collections-list.md @@ -1,4 +1,4 @@ -## Observable List +# Observable List `ObservableList` is an observable wrapper around the standard `List`, providing the same API for managing the collection. diff --git a/docs/articles/collections.md b/docs/articles/collections.md index cb1370d..5660b52 100644 --- a/docs/articles/collections.md +++ b/docs/articles/collections.md @@ -1,4 +1,4 @@ -## Observable Collections +# Observable Collections In addition to single-value observables, there are also a number of observable collections, such as `ObservableList` and `ObservableDictionary`. diff --git a/docs/articles/comparers.md b/docs/articles/comparers.md index fe3dfed..cdebc72 100644 --- a/docs/articles/comparers.md +++ b/docs/articles/comparers.md @@ -1,4 +1,4 @@ -## Custom Comparers +# Custom Comparers Observables are smart enough not to trigger bindings and recalculations when the value hasn't actually changed. This is handled on two levels: diff --git a/docs/articles/const.md b/docs/articles/const.md index b4b6576..4a1c23f 100644 --- a/docs/articles/const.md +++ b/docs/articles/const.md @@ -1,4 +1,4 @@ -## Constant Observable +# Constant Observable The most simple and lightweight kind of observable is the *const* observable for values that never change. diff --git a/docs/articles/godot.md b/docs/articles/godot.md index 188a6e2..bae8d0d 100644 --- a/docs/articles/godot.md +++ b/docs/articles/godot.md @@ -1,4 +1,4 @@ -## Godot Specifics +# Godot Specifics > **NOTE**: Godot support is currently fairly barebones and to be considered experimental. It seems to work pretty well, but it requires some amount of manual setup before using. diff --git a/docs/articles/intro.md b/docs/articles/intro.md deleted file mode 100644 index 924aecb..0000000 --- a/docs/articles/intro.md +++ /dev/null @@ -1,17 +0,0 @@ -# Introduction - -Managing and displaying large amounts of mutable data is probably the main problem of UI-centric programs, including a lot of modern games. - -We want to structure our data nicely, as well as combine, transform and cache it, and we want to make sure that changes are properly propagated and views are updated accordingly. - -TinkState# aims to simplify and streamline this. In essence, it provides: - - - Observable data structures (meaning you can read values and subscribe to changes). - - Means to define derived live-computed data from those observables (meaning changes to source values automatically updates derived values). - - Efficient binding mechanism for your code to react to changes (e.g. update the UI). - -In other worlds, TinkState# implements reactive state handling. In terms of [MVVM](https://en.wikipedia.org/wiki/Model%E2%80%93view%E2%80%93viewmodel) architecture, it covers both model and viewmodel components. - ---- - -If you're considering using TinkState# in a [Unity](https://unity.com/) project, please also check out the [Unity Specifics](unity.md) article. diff --git a/docs/articles/observable.md b/docs/articles/observable.md index 0c91d53..7dc92ac 100644 --- a/docs/articles/observable.md +++ b/docs/articles/observable.md @@ -1,4 +1,4 @@ -## Observable +# Observable The core type of this library is `Observable`. It represents observable data and its definition is pretty straightforward: @@ -19,4 +19,4 @@ So there's a getter for the current value and a way to bind a callback for its c There are multiple implementations of `Observable` and most of them can be created using static methods in the [`Observable`](xref:TinkState.Observable) helper class. -See further articles about specific kinds of observables. \ No newline at end of file +See further articles about specific kinds of observables. diff --git a/docs/articles/best-practices.md b/docs/articles/remarks.md similarity index 93% rename from docs/articles/best-practices.md rename to docs/articles/remarks.md index 8fdc4e7..5da45b3 100644 --- a/docs/articles/best-practices.md +++ b/docs/articles/remarks.md @@ -1,3 +1,5 @@ +# Remarks & Advices + ## Thread-safety This library is currently NOT thread-safe. There's no synchronization code and it uses some mutable static fields. @@ -5,4 +7,3 @@ This library is currently NOT thread-safe. There's no synchronization code and i ## Other (TODO) > TODO: state updates from bindings and computations, splitting auto-observables, binding and subscription lifetimes - diff --git a/docs/articles/state.md b/docs/articles/state.md index a09af1d..fd75b04 100644 --- a/docs/articles/state.md +++ b/docs/articles/state.md @@ -1,4 +1,4 @@ -## State +# State One important variation of `Observable` is `State`, which is a mutable observable, meaning you can also set the value: diff --git a/docs/articles/toc.yml b/docs/articles/toc.yml index 351cca7..0fa80c5 100644 --- a/docs/articles/toc.yml +++ b/docs/articles/toc.yml @@ -41,8 +41,8 @@ - name: Dictionary href: collections-dict.md -- name: Best Practices & Cautions - href: best-practices.md +- name: Remarks & Advices + href: remarks.md - name: Unity Specifics href: unity.md diff --git a/docs/articles/unity-lifetime-helper.md b/docs/articles/unity-lifetime-helper.md index bcbce1d..75b428e 100644 --- a/docs/articles/unity-lifetime-helper.md +++ b/docs/articles/unity-lifetime-helper.md @@ -1,4 +1,4 @@ -## Binding Lifetime +# Unity Binding Lifetime It is very important to dispose bindings to observables when they are no longer needed for two main reasons: @@ -81,4 +81,4 @@ var itemPool = new ObjectPool( ); itemPool.Get().Init(myData); -``` \ No newline at end of file +``` diff --git a/docs/articles/unity.md b/docs/articles/unity.md index 3c5388f..56b7ca9 100644 --- a/docs/articles/unity.md +++ b/docs/articles/unity.md @@ -1,4 +1,4 @@ -## Unity Specifics +# Unity Specifics While the base library itself is very generic and does not have any dependencies, one of the main motivations for its creation was to assist Unity developers with handling their models and view models. So this library also integrates with Unity out-of-the-box. diff --git a/docs/index.md b/docs/index.md index 8576bd2..31f640b 100644 --- a/docs/index.md +++ b/docs/index.md @@ -6,9 +6,9 @@ We want to structure our data nicely, as well as combine, transform and cache it TinkState# aims to simplify and streamline this. In essence, it provides: -- Observable data structures (meaning you can read values and subscribe to changes). -- Means to define derived live-computed data from those observables (meaning changes to source values automatically updates derived values). -- Efficient binding mechanism for your code to react to changes (e.g. update the UI). + - Observable data structures (meaning you can read values and subscribe to changes). + - Means to define derived live-computed data from those observables (meaning changes to source values automatically updates derived values). + - Efficient binding mechanism for your code to react to changes (e.g. update the UI). In other worlds, TinkState# implements reactive state handling. In terms of [MVVM](https://en.wikipedia.org/wiki/Model%E2%80%93view%E2%80%93viewmodel) architecture, it covers both model and viewmodel components.