DocC updates

- Document codable support and caveats
- Use overloaded symbols

Author: stephencelis

.spi.yml

@@ -1,5 +1,7 @@
 version: 1
 builder:
   configs:
-  - scheme: Sharing
-    documentation_targets: [Sharing]
+    - scheme: Sharing
+      documentation_targets: [Sharing]
+      custom_documentation_parameters:
+        - '--enable-experimental-overloaded-symbol-presentation'

Sources/Sharing/Documentation.docc/Articles/DerivingSharedState.md

@@ -82,7 +82,7 @@ responsible for persisting and deriving shared state to pass to the child.
 ### Optional shared state
 
 If your shared state is optional, it is possible to unwrap it as a non-optional shared value via
-``Shared/init(_:)-2z7om``.
+``Shared/init(_:)``.
 
 ```swift
 @Shared var currentUser: User?
@@ -96,8 +96,8 @@ if let loggedInUser = Shared($currentUser) {
 
 If your shared state is a collection, in particular an `IdentifiedArray`, then we have another tool
 for deriving shared state to a particular element of the array. You can pass the shared collection
-to a ``Swift/RangeReplaceableCollection``'s ``Swift/RangeReplaceableCollection/init(_:)-53j6s`` to
-create a collection of shared elements:
+to a ``Swift/RangeReplaceableCollection``'s ``Swift/RangeReplaceableCollection/init(_:)`` to create
+a collection of shared elements:
 
 ```swift
 @Shared(.fileStorage(.todos)) var todos: IdentifiedArrayOf<Todo> = []
@@ -108,8 +108,8 @@ ForEach(Array($todos)) { $todo in  // '$todo' is a 'Shared<Todo>'
 ```
 
 You can also subscript into a ``Shared`` collection with the `IdentifiedArray[id:]` subscript. This
-will give a piece of shared optional state, which you can then unwrap with the
-``Shared/init(_:)-2z7om`` initializer:
+will give a piece of shared optional state, which you can then unwrap with the ``Shared/init(_:)``
+initializer:
 
 ```swift
 @Shared(.fileStorage(.todos)) var todos: IdentifiedArrayOf<Todo> = []
@@ -121,7 +121,7 @@ todo  // Shared<Todo>
 
 ### Read-only shared state
 
-Any `@Shared` value can be made read-only via ``SharedReader/init(_:)-9wqv4``:
+Any `@Shared` value can be made read-only via ``SharedReader/init(_:)``:
 
 ```swift
 // Parent feature needs read-write access to the option

Sources/Sharing/Documentation.docc/Articles/Gotchas.md

@@ -37,7 +37,7 @@ appropriate thing.
 For example, if the data type is sharing state with a persistence strategy, you can _decode_ by 
 delegating to the memberwise initializer that implicitly loads the shared value from the property 
 wrapper's persistence strategy, or you can explicitly initialize a shared value via
-``Shared/init(wrappedValue:_:)-5xce4``. And you can _encode_ by skipping the shared value:
+``Shared/init(wrappedValue:_:)``. And you can _encode_ by skipping the shared value:
 
 ```swift
 struct TodosFeature {

Sources/Sharing/Documentation.docc/Articles/InitializationRules.md

@@ -22,10 +22,11 @@ following:
 ### Persisted @Shared state
 
 If you are using a persistence strategy with shared state (_e.g._ 
-[`appStorage`](<doc:SharedReaderKey/appStorage(_:store:)-45ltk>), [`fileStorage`](<doc:SharedReaderKey/fileStorage(_:decoder:encoder:)>),
-_etc._), then the initializer should take a plain, non-`Shared` value and you will construct
-the `Shared` value in the initializer using ``Shared/init(wrappedValue:_:)-5xce4`` which takes a
-``SharedKey`` as the second argument:
+[`appStorage`](<doc:SharedReaderKey/appStorage(_:store:)>),
+[`fileStorage`](<doc:SharedReaderKey/fileStorage(_:decoder:encoder:)>), _etc._), then the
+initializer should take a plain, non-`Shared` value and you will construct the `Shared` value in the
+initializer using ``Shared/init(wrappedValue:_:)`` which takes a ``SharedKey`` as the second
+argument:
 
 ```swift
 class FeatureModel {
@@ -45,9 +46,9 @@ argument because the persistence strategy is specified in the initializer.
 
 > Important: The value passed to this initializer is only used if the external storage does not
 > already have a value. If a value exists in the storage then it is not used. In fact, the
-> `wrappedValue` argument of ``Shared/init(wrappedValue:_:)-5xce4`` is an `@autoclosure` so that it
-> is not even evaluated if not used. For that reason you may prefer to make the argument to the
-> initializer an `@autoclosure`, as well, so that it too is evaluated only if actually used:
+> `wrappedValue` argument of ``Shared/init(wrappedValue:_:)`` is an `@autoclosure` so that it is not
+> even evaluated if not used. For that reason you may prefer to make the argument to the initializer
+> an `@autoclosure`, as well, so that it too is evaluated only if actually used:
 > 
 > ```swift
 > public struct State {

Sources/Sharing/Documentation.docc/Articles/PersistenceStrategies.md

@@ -7,7 +7,7 @@ your own custom strategies.
 
 When using `@Shared` you can supply an optional persistence strategy to represent that the state
 you are holding onto is being shared with an external system. The library ships with 3 kinds of
-strategies: [`appStorage`](<doc:SharedReaderKey/appStorage(_:store:)-45ltk>),
+strategies: [`appStorage`](<doc:SharedReaderKey/appStorage(_:store:)>),
 [`fileStorage`](<doc:SharedReaderKey/fileStorage(_:decoder:encoder:)>), and
 [`inMemory`](<doc:SharedReaderKey/inMemory(_:)>). These strategies are defined as conformances to
 the ``SharedKey`` protocol, and it is possible for you to provide your own conformances for sharing
@@ -41,7 +41,7 @@ out of sync.
 ### User defaults
 
 If you would like to persist your shared value across application launches, then you can use the
-``SharedReaderKey/appStorage(_:store:)-45ltk`` strategy with `@Shared` in order to automatically
+``SharedReaderKey/appStorage(_:store:)`` strategy with `@Shared` in order to automatically
 persist any changes to the value to user defaults. It works similarly to in-memory sharing discussed
 above. It requires a key to store the value in user defaults, as well as a default value that will
 be used when there is no value in the user defaults:

Sources/Sharing/Documentation.docc/Articles/Testing.md

@@ -13,7 +13,7 @@ trample over each other.
 Luckily the tools in this library were built with testing in mind, and you can usually test your
 features as if you were holding onto regular, non-shared state. For example, if you have a model
 that holds onto an integer that is stored in
- [`appStorage`](<doc:SharedReaderKey/appStorage(_:store:)-45ltk>) like so:
+ [`appStorage`](<doc:SharedReaderKey/appStorage(_:store:)>) like so:
 
 ```swift
 @Observable
@@ -80,7 +80,7 @@ func increment() {
 ### Testing when using custom persistence strategies
 
 When creating your own custom persistence strategies you must be careful to do so in a style that
-is amenable to testing. For example, the ``SharedReaderKey/appStorage(_:store:)-45ltk`` persistence
+is amenable to testing. For example, the ``SharedReaderKey/appStorage(_:store:)`` persistence
 strategy that comes with the library uses a ``Dependencies/DependencyValues/defaultAppStorage``
 dependency so that one can inject a custom `UserDefaults` in order to execute in a controlled
 environment. When your app runs in the simulator or on device, 

Sources/Sharing/Documentation.docc/Extensions/AppStorageKey.md

@@ -2,7 +2,7 @@
 
 A ``SharedKey`` conformance that persists simple pieces of data to user defaults, such as numbers,
 strings, booleans and URLs. It can be used with ``Shared`` by providing the 
-``SharedReaderKey/appStorage(_:store:)-45ltk`` value and specifying a default value:
+``SharedReaderKey/appStorage(_:store:)`` value and specifying a default value:
 
 ```swift
 @Shared(.appStorage("isOn")) var isOn = true
@@ -24,7 +24,7 @@ func externalWrite() {
 }
 ```
 
-### Default app storage
+## Default app storage
 
 When running your app in a simulator or device, `appStorage` will use the `standard` user defaults 
 for persisting your state. If you want to use a different user defaults, you can invoke the 
@@ -68,7 +68,7 @@ func basics() {
 }
 ```
 
-### Special characters in keys
+## Special characters in keys
 
 The `appStorage` persistence strategy can change its behavior depending on the characters its key
 contains. If the key does not contain periods (".") or at-symbols ("@"), then `appStorage` can use
@@ -93,33 +93,22 @@ prepareDependencies {
 ```
 
 > Important: We highly recommend that you avoid using periods and at-symbols in your `appStorage`
-keys. Instead you can use other delimiting symbols, such as ":", "|", "/", etc.
+> keys. Instead you can use other delimiting symbols, such as ":", "|", "/", etc.
+
+## Codable support
+
+The `appStorage` persistence strategy provides support for `Codable` types even though `@AppStorage`
+omits it for unstated reasons. If you choose to use `appStorage` with a `Codable` type, proceed with
+caution and care. Avoid large, unbounded data types, like arrays and dictionaries, which may grow
+larger than user defaults allows. If you want to share and persist an array or dictionary across
+your application, prefer [`fileStorage`](<doc:SharedReaderKey/fileStorage(_:decoder:encoder:)>),
+instead.
 
 ## Topics
 
-### Storing a value
-
-- ``SharedReaderKey/appStorage(_:store:)-45ltk``  <!-- Bool -->
-- ``SharedReaderKey/appStorage(_:store:)-vqgl``   <!-- Data -->
-- ``SharedReaderKey/appStorage(_:store:)-3dtm``   <!-- Date -->
-- ``SharedReaderKey/appStorage(_:store:)-7dai0``  <!-- Double -->
-- ``SharedReaderKey/appStorage(_:store:)-c6ap``   <!-- Int -->
-- ``SharedReaderKey/appStorage(_:store:)-5663z``  <!-- String -->
-- ``SharedReaderKey/appStorage(_:store:)-6msr0``  <!-- URL -->
-- ``SharedReaderKey/appStorage(_:store:)-2tp0t``  <!-- RawRepresentable<Int> -->
-- ``SharedReaderKey/appStorage(_:store:)-95ztf``  <!-- RawRepresentable<String> -->
-
-### Storing an optional value
-
-- ``SharedReaderKey/appStorage(_:store:)-8ys3t``  <!-- Bool? -->
-- ``SharedReaderKey/appStorage(_:store:)-1vfr4``  <!-- Data? -->
-- ``SharedReaderKey/appStorage(_:store:)-8cy6a``  <!-- Date? -->
-- ``SharedReaderKey/appStorage(_:store:)-8f3hz``  <!-- Double? -->
-- ``SharedReaderKey/appStorage(_:store:)-8bf8y``  <!-- Int? -->
-- ``SharedReaderKey/appStorage(_:store:)-4la2p``  <!-- String? -->
-- ``SharedReaderKey/appStorage(_:store:)-7fd26``  <!-- URL? -->
-- ``SharedReaderKey/appStorage(_:store:)-2vfgj``  <!-- RawRepresentable<Int?> -->
-- ``SharedReaderKey/appStorage(_:store:)-2i17q``  <!-- RawRepresentable<String?> -->
+### Storing values
+
+- ``SharedReaderKey/appStorage(_:store:)``
 
 ### Overriding app storage
 

Sources/Sharing/Documentation.docc/Extensions/Shared.md

@@ -3,7 +3,7 @@
 ## Overview
 
 Use shared state to allow for multiple parts of your application to hold onto the same piece of 
-mutable data. For example, you can have two different obsevable models hold onto a collection of 
+mutable data. For example, you can have two different observable models hold onto a collection of 
 data that is also synchronized to the file system:
 
 ```swift
@@ -34,11 +34,11 @@ also update to hold the freshest data.
 
 The `@Shared` property wrapper gives you a succinct and consistent way to persist any kind of data
 in your application. The library comes with 3 strategies:
-[`appStorage`](<doc:SharedReaderKey/appStorage(_:store:)-45ltk>),
+[`appStorage`](<doc:SharedReaderKey/appStorage(_:store:)>),
 [`fileStorage`](<doc:SharedReaderKey/fileStorage(_:decoder:encoder:)>), and
 [`inMemory`](<doc:SharedReaderKey/inMemory(_:)>). 
 
-The [`appStorage`](<doc:SharedReaderKey/appStorage(_:store:)-45ltk>) strategy is useful for store small
+The [`appStorage`](<doc:SharedReaderKey/appStorage(_:store:)>) strategy is useful for store small
 pieces of simple data in user defaults, such as settings:
 
 ```swift
@@ -109,7 +109,7 @@ See <doc:Testing> for more information on how to test your features when using `
 
 ### Creating a persisted value
 
-- ``init(wrappedValue:_:)-5xce4``
+- ``init(wrappedValue:_:)``
 
 ### Creating a shared value
 
@@ -118,9 +118,8 @@ See <doc:Testing> for more information on how to test your features when using `
 
 ### Transforming a shared value
 
-- ``subscript(dynamicMember:)-68021``
-- ``subscript(dynamicMember:)-318vw``
-- ``init(_:)-2z7om``
+- ``subscript(dynamicMember:)``
+- ``init(_:)``
 
 ### Accessing the value
 

Sources/Sharing/Documentation.docc/Extensions/SharedInit.md

@@ -57,7 +57,7 @@ if remoteConfig.isToggleEnabled {
 
 ### Creating a persisted reader
 
-- ``init(wrappedValue:_:)-56tir``
+- ``init(wrappedValue:_:)``
 
 ### Creating a shared reader
 
@@ -66,10 +66,8 @@ if remoteConfig.isToggleEnabled {
 
 ### Transforming a shared value
 
-- ``subscript(dynamicMember:)-3jfdr``
-- ``init(_:)-9wqv4``
-- ``init(_:)-9ka0y``
-- ``init(_:)-498ca``
+- ``subscript(dynamicMember:)``
+- ``init(_:)``
 
 ### Reading the value