Add xmldocs for IsPhantom

Author: Mpdreamz

src/Elastic.Documentation.Configuration/TableOfContents/ITocItem.cs

@@ -23,6 +23,19 @@ public record TocReference(Uri Source, ITableOfContentsScope TableOfContentsScop
 	public IReadOnlyDictionary<Uri, TocReference> TocReferences { get; } =
 		Children.OfType<TocReference>().ToDictionary(kv => kv.Source, kv => kv);
 
+	/// <summary>
+	/// A phantom table of contents is a table of contents that is not rendered in the UI but is used to generate the TOC.
+	/// This should be used sparingly and needs explicit configuration in navigation.yml.
+	/// It's typically used for container TOC that holds various other TOC's where its children are rehomed throughout the navigation.
+	/// <para>Examples of phantom toc's:</para>
+	/// <list type="">
+	///		<item> - toc: elasticsearch://reference</item>
+	///		<item> - toc: docs-content://</item>
+	/// </list>
+	/// <para>Because navigation.yml does exhaustive checks to ensure all toc.yml files are referenced, marking these containers as phantoms
+	/// ensures that these skip validation checks
+	/// </para>
+	/// </summary>
 	public bool IsPhantom { get; init; }
 }
 

src/Elastic.Markdown/IO/Navigation/DocumentationGroup.cs

@@ -221,10 +221,9 @@ void AddToNavigationItems(INavigationItem item, ref int fileIndex)
 					continue;
 				}
 
-				//var navigationIndex = Interlocked.Increment(ref fileIndex);
-				//md.NavigationIndex = navigationIndex;
 				md.PartOfNavigation = true;
 
+				// TODO these have to be refactor to be pure navigational properties
 				md.ScopeDirectory = file.TableOfContentsScope.ScopeDirectory;
 				md.NavigationRoot = topLevelGroup;
 				md.NavigationSource = NavigationSource;