Write docs for DependencyPropertyGenerator

components/DependencyPropertyGenerator/samples/DependencyPropertyGenerator.md

@@ -0,0 +1,110 @@
+---
+title: DependencyPropertyGenerator
+author: Sergio0694
+description: A source generator for DependencyProperty registration.
+keywords: DependencyPropertyGenerator
+dev_langs:
+  - csharp
+category: Xaml
+subcategory: Developer
+experimental: true
+discussion-id: 449
+issue-id: 621
+icon: Assets/DependencyPropertyGenerator.png
+---
+
+The `DependencyPropertyGenerator` is a source generator that simplifies the registration of `DependencyProperty` fields in your XAML projects.
+It automatically generates the boilerplate code needed for property registration, making it easier to work with dependency properties.
+
+Dependency properties are a key feature in WinUI, allowing for property value inheritance, change notification, and data binding.
+
+## Features
+
+- Automatically generates dependency property boilerplate code.
+- Supports customization through attributes.
+- Ensures consistency and reduces manual errors.
+- Improves readability and maintainability of code.
+
+Like other Windows Community Toolkit components, the `DependencyPropertyGenerator` supports UWP, Uno Platform and the Windows App SDK.
+
+## Using `GeneratedDependencyPropertyAttribute`
+
+To use the `DependencyPropertyGenerator`, you need to add the `GeneratedDependencyPropertyAttribute` to your properties.
+This attribute specifies the name of the dependency property and its default value.
+
+> Other DP generators might prefer using an attribute on the class instead, however the Community Toolkit's generator requires you to put the attribute on individual properties.
+
+For example, if you were to consume the `DependencyPropertyGenerator` from UWP:
+
+```cs
+namespace MyNamespace;
+
+public partial class MyControl : DependencyObject
+{
+    // The GeneratedDependencyPropertyAttribute is used to specify which property to generate the DependencyProperty for.
+    [GeneratedDependencyProperty(IsLocalCacheEnabled = true)]
+    // It is required that you mark the property as partial, so that the generator can add additional code to its get() method.
+    public partial int Number { get; set; }
+}
+```
+
+The source generator would generate the following partial methods:
+
+- `OnNumberSet`: "Executes the logic for when the `set` accessor `Number` is invoked"
+- `OnNumberChanging`: "Executes the logic for when `Number` is changing."
+- `OnNumberChanged`: "Executes the logic for when `Number` has just changed."
+- `OnNumberPropertyChanged`: "Executes the logic for when `Number` has just changed."
+- `OnPropertyChanged`: "Executes the logic for when any dependency property has just changed."
+
+Alongside the following changes to the `Number` property:
+
+```cs
+public partial int Number
+{
+    get => field;
+    set
+    {
+        OnNumberSet(ref value);
+
+        if (EqualityComparer<int>.Default.Equals(field, value))
+        {
+            return;
+        }
+
+        int __oldValue = field;
+
+        OnNumberChanging(value);
+        OnNumberChanging(__oldValue, value);
+
+        field = value;
+
+        object? __boxedValue = value;
+
+        OnNumberSet(ref __boxedValue);
+
+        SetValue(NumberProperty, __boxedValue);
+
+        OnNumberChanged(value);
+        OnNumberChanged(__oldValue, value);
+    }
+}
+```
+
+The `DependencyPropertyGenerator` of course also generates the DP registration code itself, aside from the helpful methods listed above.
+
+For the `Number` property mentioned earlier, the generator would create a static field called `NumberProperty`:
+
+```cs
+/// <summary>
+/// The backing <see cref="DependencyProperty"/> instance for <see cref="Number"/>.
+/// </summary>
+public static readonly DependencyProperty NumberProperty = DependencyProperty.Register(
+    name: "Number",
+    propertyType: typeof(int),
+    ownerType: typeof(MyControl),
+    typeMetadata: null);
+```
+
+
+
+> [!Sample DependencyPropertyGeneratorCustomSample]

components/DependencyPropertyGenerator/samples/DependencyPropertyGeneratorCustomSample.xaml

@@ -0,0 +1,17 @@
+<!--  Licensed to the .NET Foundation under one or more agreements. The .NET Foundation licenses this file to you under the MIT license. See the LICENSE file in the project root for more information.  -->
+<Page
+    x:Class="DependencyPropertyGenerator.Samples.DependencyPropertyGeneratorCustomSample"
+    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
+    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
+    xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
+    xmlns:local="using:DependencyPropertyGenerator.Samples"
+    xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
+    mc:Ignorable="d">
+    <Grid>
+        <TextBlock
+            HorizontalAlignment="Center"
+            VerticalAlignment="Center"
+            FontSize="24"
+            Text="This is a custom sample for the DependencyPropertyGenerator." />
+    </Grid>
+</Page>

components/DependencyPropertyGenerator/samples/DependencyPropertyGeneratorCustomSample.xaml.cs

@@ -0,0 +1,16 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+// See the LICENSE file in the project root for more information.
+
+using CommunityToolkit.WinUI;
+
+namespace DependencyPropertyGenerator.Samples;
+
+[ToolkitSample(id: nameof(DependencyPropertyGeneratorCustomSample), "Custom control", description: $"A sample for showing how to use {nameof(GeneratedDependencyPropertyAttribute)} to register dependency properties.")]
+public sealed partial class DependencyPropertyGeneratorCustomSample : Page
+{
+    public DependencyPropertyGeneratorCustomSample()
+    {
+        this.InitializeComponent();
+    }
+}