Add documentation comments section to coding guidelines (PowerShell#14316)

xtqqczze · web-flow · commit 1b952a0cd5c3 · 2021-04-20T09:15:54.000-04:00
diff --git a/.spelling b/.spelling
@@ -383,6 +383,7 @@ includeusername
 informationrecord
 initializers
 install-packageprovider
+IntelliSense
 interactivetesting
 interop
 interoperation
diff --git a/docs/dev-process/coding-guidelines.md b/docs/dev-process/coding-guidelines.md
@@ -86,9 +86,15 @@ We also run the [.NET code formatter tool](https://github.com/dotnet/codeformatt
 
 * Make sure the added/updated comments are meaningful, accurate and easy to understand.
 
-* Public members must use [doc comments](https://docs.microsoft.com/dotnet/csharp/programming-guide/xmldoc/).
+### Documentation comments
+
+* Create documentation using [XML documentation comments](https://docs.microsoft.com/dotnet/csharp/codedoc) so that Visual Studio and other IDEs can use IntelliSense to show quick information about types or members.
+
+* Publicly visible types and their members must be documented.
   Internal and private members may use doc comments but it is not required.
 
+* Documentation text should be written using complete sentences ending with full stops.
+
 ## Performance Considerations
 
 PowerShell has a lot of performance sensitive code as well as a lot of inefficient code.
