From 7a329be400a39cf9a1e3570c81769e4cb7dad1df Mon Sep 17 00:00:00 2001
From: Ben McCallum <ben.mccallum@live.com.au>
Date: Tue, 18 Jan 2022 21:01:30 +0100
Subject: [PATCH] Add note for xml docs + custom naming convention (#4661)

---
 .../api-reference/migrate-from-11-to-12.md    | 42 +++++++++++++++++++
 .../defining-a-schema/documentation.md        | 35 ++++++++++++++++
 2 files changed, 77 insertions(+)

diff --git a/website/src/docs/hotchocolate/api-reference/migrate-from-11-to-12.md b/website/src/docs/hotchocolate/api-reference/migrate-from-11-to-12.md
index 0764e9d8782..f9dbb55f706 100644
--- a/website/src/docs/hotchocolate/api-reference/migrate-from-11-to-12.md
+++ b/website/src/docs/hotchocolate/api-reference/migrate-from-11-to-12.md
@@ -275,3 +275,45 @@ public class CustomBatchDataLoader : BatchDataLoader<string, string?>
 ```
 
 Allowing the DI to inject the options will allow the DataLoader to use the new shared pooled cache objects.
+
+# Custom naming conventions
+
+If you're using a custom naming convention and have xml documentation enabled, you'll need to modify the way the naming convention is hooked up
+else your comments will disappear from your schema.
+
+**v11**
+
+```csharp
+public class CustomNamingConventions : DefaultNamingConventions
+{
+    public CustomNamingConventions()
+        : base() { }
+}
+
+services
+    .AddGraphQLServer()
+    .AddConvention<INamingConventions>(sp => new CustomNamingConventions()) // or
+    .AddConvention<INamingConventions, CustomNamingConventions>();
+```  
+
+**v12**
+
+```csharp
+public class CustomNamingConventions : DefaultNamingConventions
+{
+    public CustomNamingConventions(IDocumentationProvider documentationProvider)
+        : base(documentationProvider) { }
+}
+
+IReadOnlySchemaOptions capturedSchemaOptions;  
+services
+    .AddGraphQLServer()
+    .ModifyOptions(opt => capturedSchemaOptions = opt)
+    .AddConvention<INamingConventions>(sp => new CustomNamingConventions(
+        new XmlDocumentationProvider(
+            new XmlDocumentationFileResolver(
+                capturedSchemaOptions.ResolveXmlDocumentationFileName),
+            sp.GetApplicationService<ObjectPool<StringBuilder>>() 
+                ?? new NoOpStringBuilderPool())));
+```  
+
diff --git a/website/src/docs/hotchocolate/defining-a-schema/documentation.md b/website/src/docs/hotchocolate/defining-a-schema/documentation.md
index 42592345308..4f524be0f89 100644
--- a/website/src/docs/hotchocolate/defining-a-schema/documentation.md
+++ b/website/src/docs/hotchocolate/defining-a-schema/documentation.md
@@ -211,3 +211,38 @@ services
     .AddGraphQLServer()
     .ModifyOptions(opt => opt.UseXmlDocumentation = false);
 ```
+
+## With a custom naming convention
+
+If you want to use a custom naming convention and XML documentation, ensure you give the convention an instance of the `XmlDocumentationProvider` as demonstrated below; otherwise the comments won't appear in your schema.
+
+```csharp
+public class CustomNamingConventions : DefaultNamingConventions
+{
+    // Before
+    public CustomNamingConventions()
+        : base() { }
+  
+    // After
+    public CustomNamingConventions(IDocumentationProvider documentationProvider)
+        : base(documentationProvider) { }
+}
+
+// Startup
+// Before
+.AddConvention<INamingConventions>(sp => new CustomNamingConventions());
+
+// After
+IReadOnlySchemaOptions capturedSchemaOptions;
+  
+services
+    .AddGraphQLServer()
+    .ModifyOptions(opt => capturedSchemaOptions = opt)
+    .AddConvention<INamingConventions>(sp => new CustomNamingConventions(
+        new XmlDocumentationProvider(
+            new XmlDocumentationFileResolver(
+                capturedSchemaOptions.ResolveXmlDocumentationFileName),
+            sp.GetApplicationService<ObjectPool<StringBuilder>>() 
+              ?? new NoOpStringBuilderPool())));
+```  
+