Merge pull request #145 from annulusgames/update-docs

chore: Improve documents

Author: paq

Alchemy.SourceGenerator/README.md

@@ -2,7 +2,7 @@
 
 Source generator for Alchemy.
 
-# How to update the shipped DLL
+## How to update the shipped DLL
 
 Unity consumes the compiled generator at
 `Alchemy/Assets/Alchemy/Generator/Alchemy.SourceGenerator.dll`. After changing the generator, rebuild it with:

README.md

@@ -8,9 +8,9 @@
 
 ## Overview
 
-Alchemy is a library that provides Inspector extensions using attributes.
+Alchemy is a library that provides attribute-based Inspector extensions.
 
-In addition to providing easy and powerful attribute-based editor extensions, it allows serialization of any types (Dictionary, HashSet, Nullable, Tuple, etc.) via its own serialization system, so those types can be edited in the Inspector. Alchemy works simply by adding attributes to the target type — just mark it as `partial`, and a Source Generator creates the necessary code. Unlike Odin, there is no need to inherit from dedicated base classes.
+In addition to providing easy and powerful attribute-based editor extensions, Alchemy can serialize types that Unity does not normally support, such as dictionaries, hash sets, nullable value types, and tuples, so they can be edited in the Inspector. Add the appropriate attributes to a target type and mark it as `partial`; a source generator creates the necessary code. Unlike Odin, there is no need to inherit from dedicated base classes.
 
 <img src="https://github.com/annulusgames/Alchemy/blob/main/docs/images/img-v2.0.png" width="800">
 
@@ -20,7 +20,7 @@ v2.0 also adds EditorWindow and Hierarchy extensions. These make it easy to buil
 
 * Add over 30 attributes to extend the Inspector
 * Support SerializeReference, allowing selection of types from a dropdown
-* Serialize any type (Dictionary, HashSet, Nullable, Tuple, etc.) and edit them in the Inspector
+* Serialize additional types, including dictionaries, hash sets, nullable value types, and tuples, and edit them in the Inspector
 * Create EditorWindows using attributes
 * Improve Hierarchy usability
 * Create custom attributes that work with Alchemy
@@ -29,20 +29,20 @@ v2.0 also adds EditorWindow and Hierarchy extensions. These make it easy to buil
 
 ### Requirements
 
-* Unity 2021.2 or higher (Recommended: 2022.1 or higher for serialization extensions)
-* Unity Serialization 2.0 or higher (for serialization extensions)
+* Unity 2021.2 or later (Unity 2022.1 or later is recommended for serialization extensions)
+* Unity.Serialization 2.0 or later (for serialization extensions)
 
 ### Installation
 
-1. Open Package Manager from Window > Package Manager
+1. Open the Package Manager from Window > Package Manager
 2. Click the "+" button > Add package from git URL
 3. Enter the following URL:
 
 ```
 https://github.com/annulusgames/Alchemy.git?path=/Alchemy/Assets/Alchemy
 ```
 
-Or open Packages/manifest.json and add the following to the dependencies block:
+Alternatively, open `Packages/manifest.json` and add the following entry to the `dependencies` block:
 
 ```json
 {
@@ -124,7 +124,7 @@ using UnityEngine;
 using Alchemy.Inspector;
 
 [Serializable]
-public sealed class Example : IExample
+public sealed class Example
 {
     public float foo;
     public Vector3 bar;
@@ -213,7 +213,7 @@ Alchemy provides several features that extend the Hierarchy.
 
 <img src="https://github.com/annulusgames/Alchemy/blob/main/docs/images/gif-hierarchy-toggle.gif" width="600">
 
-You can add toggles for each object's active/inactive state and icons that show its components to the Hierarchy. These can be configured from Project Settings.
+You can display active-state toggles and component icons for each object in the Hierarchy. These features can be configured in Project Settings.
 
 <img src="https://github.com/annulusgames/Alchemy/blob/main/docs/images/img-project-settings.png" width="600">
 
@@ -223,8 +223,8 @@ From the Create menu, you can create objects that decorate the Hierarchy.
 
 <img src="https://github.com/annulusgames/Alchemy/blob/main/docs/images/img-create-hierarchy-object.png" width="600">
 
-These objects are automatically excluded from builds. (If they have child objects, any child objects are unparented before deletion.)
-For more details, refer to [Decorating Hierarchy](https://annulusgames.github.io/Alchemy/articles/en/decorating-hierarchy.html).
+These objects are automatically excluded from builds. If they have children, the children are unparented before the decorative objects are deleted.
+For more details, refer to [Decorating the Hierarchy](https://annulusgames.github.io/Alchemy/articles/en/decorating-hierarchy.html).
 
 ## AlchemyEditorWindow
 
@@ -278,11 +278,11 @@ public class EditorWindowExample : AlchemyEditorWindow
 
 <img src="https://github.com/annulusgames/Alchemy/blob/main/docs/images/img-editor-window.png" width="600">
 
-Data for windows that inherit from `AlchemyEditorWindow` is saved as JSON in the project's ProjectSettings folder. For more details, refer to [Saving Editor Window Data](https://annulusgames.github.io/Alchemy/articles/en/saving-editor-window-data.html).
+Data for windows that inherit from `AlchemyEditorWindow` is saved as JSON in the project's `ProjectSettings` folder. For more details, refer to [Saving Editor Window Data](https://annulusgames.github.io/Alchemy/articles/en/saving-editor-window-data.html).
 
 ## Using Serialization Extensions
 
-If you want to edit types that Unity cannot serialize, such as Dictionary, you can use the `[AlchemySerialize]` attribute to serialize these types.
+To edit types that Unity does not normally serialize, such as dictionaries, use the `[AlchemySerialize]` attribute.
 
 Serialization extensions require the [Unity.Serialization](https://docs.unity3d.com/Packages/com.unity.serialization@3.1/manual/index.html) package. Additionally, reflection-based serialization using Unity.Serialization may not work in AOT environments prior to Unity 2022.1. Check the package manual for details.
 
@@ -295,7 +295,7 @@ using UnityEngine;
 using Alchemy.Serialization;
 
 // By adding the [AlchemySerialize] attribute, Alchemy's serialization extension is enabled.
-// It can be used with any type, regardless of its base class, but the target type must be partial for the Source Generator to generate code.
+// It can be used regardless of the target type's base class, but the target type must be partial for the source generator to generate code.
 [AlchemySerialize]
 public partial class AlchemySerializationExample : MonoBehaviour
 {

docs/articles/en/about.md

@@ -2,8 +2,8 @@
 
 ![header](../../images/header.png)
 
-Alchemy is a library that provides a rich set of editor extensions for Unity. By integrating Alchemy, over 30 attributes are added to easily extend the Inspector. Additionally, by utilizing the Unity.Serialization package and a dedicated Source Generator, it becomes possible to serialize and edit types not normally serializable in Unity (`Dictionary`, `HashSet`, `Nullable`, `ValueTuple`, etc.) directly from the Inspector.
+Alchemy is a library that provides a rich set of editor extensions for Unity. It includes more than 30 attributes that make it easy to extend the Inspector. With the Unity.Serialization package and a dedicated source generator, Alchemy can also serialize and edit types that Unity does not normally support, including `Dictionary`, `HashSet`, `Nullable`, and `ValueTuple`.
 
 ![img](../../images/img-v2.0.png)
 
-Furthermore, version 2.0 introduces new features such as EditorWindow extensions and Hierarchy extensions. These enable the easy creation of tools to streamline the development workflow within the editor.
+Version 2.0 also introduces editor-window and Hierarchy extensions. These features make it easy to build tools that streamline development workflows in the Unity Editor.

docs/articles/en/alchemy-editor-window.md

@@ -50,4 +50,4 @@ public class EditorWindowExample : AlchemyEditorWindow
 
 ![img](../../images/img-editor-window.png)
 
-Data from windows created by inheriting `AlchemyEditorWindow` is saved in JSON format in the ProjectSettings folder of the project. For more details, refer to the [Saving Editor Window Data](saving-editor-window-data.md) page.
+Data for windows derived from `AlchemyEditorWindow` is saved as JSON in the project's `ProjectSettings` folder. For more details, refer to [Saving Editor Window Data](saving-editor-window-data.md).

docs/articles/en/alchemy-serialization-process.md

@@ -1,6 +1,6 @@
 # Alchemy Serialization Process
 
-In Alchemy, by adding the `[AlchemySerialize]` attribute to the target type, a dedicated Source Generator automatically implements `ISerializationCallbackReceiver`. Within this process, all fields annotated with `[AlchemySerializeField]` are gathered, and using the Unity.Serialization package, they are converted to JSON format. However, fields of type `UnityEngine.Object` cannot be handled in JSON format, so their instances are saved in a single list, and only their indices are written to JSON.
+Adding `[AlchemySerialize]` to a target type causes Alchemy's source generator to implement `ISerializationCallbackReceiver`. It collects all fields marked with `[AlchemySerializeField]` and uses the Unity.Serialization package to serialize their data to JSON. Because references to `UnityEngine.Object` instances cannot be represented directly in JSON, Alchemy stores them in a separate list and writes their indices to the JSON data.
 
 For example, consider the following class:
 
@@ -77,4 +77,4 @@ partial class AlchemySerializationExample : global::UnityEngine.ISerializationCa
 }
 ```
 
-Using `[AlchemySerializeField]` increases the processing load for serialization and deserialization. Therefore, it is recommended to avoid using `[AlchemySerializeField]` whenever possible.
+Using `[AlchemySerializeField]` adds serialization and deserialization overhead. Use it only for fields that Unity cannot serialize normally.

docs/articles/en/attributes/assets-only.md

@@ -1,6 +1,6 @@
 # Assets Only Attribute
 
-Limits the reference that can be entered into an object field to assets only.
+Restricts an object field to asset references.
 
 ![img](../../../images/img-attribute-assets-only.png)
 
@@ -10,4 +10,4 @@ public Object asset1;
 
 [AssetsOnly]
 public GameObject asset2;
-```
+```

docs/articles/en/attributes/blockquote.md

@@ -11,4 +11,4 @@ public float foo;
 
 | Parameter | Description |
 | - | - |
-| Text | The text to display in the quotation |
+| Text | The text to display in the quotation |

docs/articles/en/attributes/box-group.md

@@ -26,4 +26,4 @@ public GameObject gamma;
 
 | Parameter | Description |
 | - | - |
-| GroupPath | Specifies the path of the group. Groups can be nested by separating them with `/`. |
+| GroupPath | Specifies the path of the group. Groups can be nested by separating them with `/`. |

docs/articles/en/attributes/button.md

@@ -27,4 +27,4 @@ public void Foo(SampleClass parameter)
     builder.Append("baz = ").Append(parameter.baz == null ? "Null" : parameter.baz.ToString());
     Debug.Log("Foo: " + builder.ToString());
 }
-```
+```

docs/articles/en/attributes/disable-alchemy-editor.md

@@ -1,6 +1,6 @@
 # Disable Alchemy Editor Attribute
 
-Disables the AlchemyEditor for the target class and uses the default Inspector for rendering. When this attribute is added to a field, only that field will be rendered using the default PropertyField.
+Disables `AlchemyEditor` for the target class and uses the default Inspector instead. When this attribute is added to a field, only that field is rendered using the default `PropertyField`.
 
 ![img](../../../images/img-attribute-disable-alchemy-editor.png)
 
@@ -12,4 +12,4 @@ public class DisableAlchemyEditorExample : MonoBehaviour
     public Vector3 bar;
     public GameObject baz;
 }
-```
+```