From b07df634224443152e8d4aebce967c12fe2c39f4 Mon Sep 17 00:00:00 2001
From: Shannon <sdeminick@gmail.com>
Date: Fri, 19 Jul 2019 15:49:39 +1000
Subject: [PATCH] Adds some better notes to the api docs

---
 src/Umbraco.Core/PublishedContentExtensions.cs | 16 ++++++++++++++--
 1 file changed, 14 insertions(+), 2 deletions(-)

diff --git a/src/Umbraco.Core/PublishedContentExtensions.cs b/src/Umbraco.Core/PublishedContentExtensions.cs
index e09e76d06a..921883b822 100644
--- a/src/Umbraco.Core/PublishedContentExtensions.cs
+++ b/src/Umbraco.Core/PublishedContentExtensions.cs
@@ -103,11 +103,23 @@ namespace Umbraco.Core
         /// Gets the children of the content item.
         /// </summary>
         /// <param name="content">The content item.</param>
-        /// <param name="culture">The specific culture to get the url children for. If null is used the current culture is used (Default is null).</param>
+        /// <param name="culture">
+        /// The specific culture to get the url children for. Default is null which will use the current culture in <see cref="VariationContext"/>        
+        /// </param>
         /// <remarks>
         /// <para>Gets children that are available for the specified culture.</para>
         /// <para>Children are sorted by their sortOrder.</para>
-        /// <para>The '*' culture and supported and returns everything.</para>
+        /// <para>
+        /// For culture, 
+        /// if null is used the current culture is used.
+        /// If an empty string is used only invariant children are returned.
+        /// If "*" is used all children are returned.
+        /// </para>
+        /// <para>
+        /// If a variant culture is specified or there is a current culture in the <see cref="VariationContext"/> then the Children returned
+        /// will include both the variant children matching the culture AND the invariant children because the invariant children flow with the current culture.
+        /// However, if an empty string is specified only invariant children are returned.
+        /// </para>
         /// </remarks>
         public static IEnumerable<IPublishedContent> Children(this IPublishedContent content, string culture = null)
         {