Add note for xml docs + custom naming convention (#4661)

ChilliCream · Jan 18, 2022 · 7a329be · 7a329be
1 parent f3a4011
commit 7a329be
Show file tree

Hide file tree

Showing 2 changed files with 77 additions and 0 deletions.
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
@@ -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
@@ -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())));
+```  
+