Collections XML docs migration and runnable code samples

eng/run-samples.sh

@@ -0,0 +1,124 @@
+#!/usr/bin/env bash
+
+set -uo pipefail
+
+source="${BASH_SOURCE[0]}"
+while [[ -h "$source" ]]; do
+  scriptroot="$( cd -P "$( dirname "$source" )" && pwd )"
+  source="$(readlink "$source")"
+  [[ $source != /* ]] && source="$scriptroot/$source"
+done
+scriptroot="$( cd -P "$( dirname "$source" )" && pwd )"
+reporoot="$( cd -P "$scriptroot/.." && pwd )"
+
+usage()
+{
+  echo "Usage: run-samples.sh [options]"
+  echo ""
+  echo "Discovers and runs all *.Examples.cs sample files under src/libraries/*/samples/."
+  echo "Each sample is a file-based app executed with 'dotnet run'. A non-zero exit code"
+  echo "from any sample is treated as a failure."
+  echo ""
+  echo "Options:"
+  echo "  --verbose (-v)    Show output from every sample, not just failures."
+  echo "  --help (-h)       Print this help message."
+  echo ""
+  echo "Examples:"
+  echo "  ./eng/run-samples.sh              # Run all samples, report failures"
+  echo "  ./eng/run-samples.sh --verbose    # Run all samples, show all output"
+}
+
+verbose=false
+
+while [[ $# -gt 0 ]]; do
+  opt="$(echo "${1/#--/-}" | tr "[:upper:]" "[:lower:]")"
+  case "$opt" in
+    -help|-h|-\?)
+      usage
+      exit 0
+      ;;
+    -verbose|-v)
+      verbose=true
+      shift 1
+      ;;
+    *)
+      echo "Unknown option: $1" 1>&2
+      usage
+      exit 1
+      ;;
+  esac
+done
+
+export PATH="$reporoot/.dotnet:$PATH"
+
+# Verify the SDK is available.
+if ! command -v dotnet &> /dev/null; then
+  echo "error: 'dotnet' not found. Build the repo first (./build.sh) to provision the SDK."
+  exit 1
+fi
+
+# Discover all sample files.
+mapfile -t sample_files < <(find "$reporoot/src/libraries" -path '*/samples/*/*.Examples.cs' -type f | sort)
+
+if [[ ${#sample_files[@]} -eq 0 ]]; then
+  echo "No sample files found."
+  exit 0
+fi
+
+echo "Found ${#sample_files[@]} sample file(s)."
+echo ""
+
+passed=0
+failed=0
+declare -a failed_files=()
+
+for file in "${sample_files[@]}"; do
+  # Determine the samples/ directory (where Directory.Build.props lives).
+  samples_dir="${file}"
+  while [[ "$(basename "$samples_dir")" != "samples" ]]; do
+    samples_dir="$(dirname "$samples_dir")"
+  done
+
+  # Build a relative path from the samples dir to the .cs file.
+  relative_path="${file#"$samples_dir/"}"
+
+  # Friendly display name: library + relative path.
+  lib_dir="$(dirname "$samples_dir")"
+  lib_name="$(basename "$lib_dir")"
+  display_name="$lib_name/samples/$relative_path"
+
+  echo -n "  Running $display_name ... "
+
+  # Run the sample from the samples/ directory.
+  output=$(cd "$samples_dir" && dotnet run "$relative_path" 2>&1)
+  exit_code=$?
+
+  if [[ $exit_code -eq 0 ]]; then
+    echo "passed"
+    ((passed++))
+    if [[ "$verbose" == true ]]; then
+      echo "$output" | sed 's/^/    | /'
+    fi
+  else
+    echo "FAILED (exit code $exit_code)"
+    ((failed++))
+    failed_files+=("$display_name")
+    echo "$output" | sed 's/^/    | /'
+  fi
+done
+
+echo ""
+echo "=========================================="
+echo "  Samples: $((passed + failed))  Passed: $passed  Failed: $failed"
+echo "=========================================="
+
+if [[ $failed -gt 0 ]]; then
+  echo ""
+  echo "Failed samples:"
+  for f in "${failed_files[@]}"; do
+    echo "  - $f"
+  done
+  exit 1
+fi
+
+exit 0

src/libraries/System.Collections/samples/Directory.Build.props

@@ -0,0 +1,11 @@
+<Project>
+  <!-- Stop inheriting repo-wide settings that break file-based app samples. -->
+  <PropertyGroup>
+    <TargetFramework>net11.0</TargetFramework>
+    <PublishAot>false</PublishAot>
+    <IsAotCompatible>false</IsAotCompatible>
+    <IsSourceProject>false</IsSourceProject>
+    <IsReferenceAssemblyProject>false</IsReferenceAssemblyProject>
+    <TreatWarningsAsErrors>false</TreatWarningsAsErrors>
+  </PropertyGroup>
+</Project>

src/libraries/System.Collections/samples/Directory.Build.targets

@@ -0,0 +1,2 @@
+<Project>
+</Project>

src/libraries/System.Collections/samples/System/Collections/Generic/LinkedList.Examples.cs

@@ -0,0 +1,94 @@
+using System;
+using System.Collections.Generic;
+
+AddNodes();
+RemoveNodes();
+FindNodes();
+NavigateNodes();
+CopyToArray();
+
+void AddNodes()
+{
+    var list = new LinkedList<string>();
+
+    list.AddFirst("B");
+    list.AddFirst("A");
+    list.AddLast("D");
+
+    LinkedListNode<string> nodeB = list.Find("B")!;
+    list.AddAfter(nodeB, "B+");
+    list.AddBefore(nodeB, "B-");
+
+    foreach (string item in list)
+        Console.Write(item + " ");
+    Console.WriteLine();
+    // Output: A B- B B+ D
+}
+
+void RemoveNodes()
+{
+    var list = new LinkedList<string>(new[] { "A", "B", "C", "D", "E" });
+
+    list.RemoveFirst();
+    list.RemoveLast();
+    list.Remove("C");
+
+    foreach (string item in list)
+        Console.Write(item + " ");
+    Console.WriteLine();
+    // Output: B D
+
+    list.Clear();
+    Console.WriteLine($"Count after Clear: {list.Count}");
+    // Output: Count after Clear: 0
+}
+
+void FindNodes()
+{
+    var list = new LinkedList<int>(new[] { 1, 2, 3, 2, 1 });
+
+    LinkedListNode<int>? first2 = list.Find(2);
+    LinkedListNode<int>? last2 = list.FindLast(2);
+
+    Console.WriteLine($"Find(2) next: {first2!.Next!.Value}");
+    // Output: Find(2) next: 3
+    Console.WriteLine($"FindLast(2) next: {last2!.Next!.Value}");
+    // Output: FindLast(2) next: 1
+    Console.WriteLine($"Contains(3): {list.Contains(3)}");
+    // Output: Contains(3): True
+}
+
+void NavigateNodes()
+{
+    var list = new LinkedList<string>(new[] { "A", "B", "C" });
+
+    LinkedListNode<string>? node = list.First;
+    Console.WriteLine($"First: {node!.Value}");
+    // Output: First: A
+    Console.WriteLine($"Last: {list.Last!.Value}");
+    // Output: Last: C
+    Console.WriteLine($"Count: {list.Count}");
+    // Output: Count: 3
+
+    Console.WriteLine($"First.Next: {node.Next!.Value}");
+    // Output: First.Next: B
+    Console.WriteLine($"Last.Previous: {list.Last!.Previous!.Value}");
+    // Output: Last.Previous: B
+    Console.WriteLine($"First.List == list: {node.List == list}");
+    // Output: First.List == list: True
+
+    ref string valueRef = ref node.ValueRef;
+    valueRef = "Z";
+    Console.WriteLine($"First after ValueRef mutation: {list.First!.Value}");
+    // Output: First after ValueRef mutation: Z
+}
+
+void CopyToArray()
+{
+    var list = new LinkedList<int>(new[] { 10, 20, 30 });
+    int[] array = new int[5];
+    list.CopyTo(array, 1);
+
+    Console.WriteLine(string.Join(", ", array));
+    // Output: 0, 10, 20, 30, 0
+}

src/libraries/System.Collections/samples/System/Collections/Generic/LinkedList.samples.json

@@ -0,0 +1,161 @@
+{
+  "T:System.Collections.Generic.LinkedList`1": {
+    "file": "System/Collections/Generic/LinkedList.Examples.cs",
+    "method": "AddNodes",
+    "title": "Adding nodes to a LinkedList",
+    "primary": true
+  },
+  "M:System.Collections.Generic.LinkedList`1.#ctor": {
+    "file": "System/Collections/Generic/LinkedList.Examples.cs",
+    "method": "RemoveNodes",
+    "title": "Removing nodes from a LinkedList",
+    "primary": true
+  },
+  "M:System.Collections.Generic.LinkedList`1.#ctor(System.Collections.Generic.IEnumerable{`0})": {
+    "file": "System/Collections/Generic/LinkedList.Examples.cs",
+    "method": "RemoveNodes",
+    "title": "Removing nodes from a LinkedList"
+  },
+  "M:System.Collections.Generic.LinkedList`1.AddFirst(`0)": {
+    "file": "System/Collections/Generic/LinkedList.Examples.cs",
+    "method": "AddNodes",
+    "title": "Adding nodes to a LinkedList"
+  },
+  "M:System.Collections.Generic.LinkedList`1.AddFirst(System.Collections.Generic.LinkedListNode{`0})": {
+    "file": "System/Collections/Generic/LinkedList.Examples.cs",
+    "method": "AddNodes",
+    "title": "Adding nodes to a LinkedList"
+  },
+  "M:System.Collections.Generic.LinkedList`1.AddLast(`0)": {
+    "file": "System/Collections/Generic/LinkedList.Examples.cs",
+    "method": "AddNodes",
+    "title": "Adding nodes to a LinkedList"
+  },
+  "M:System.Collections.Generic.LinkedList`1.AddLast(System.Collections.Generic.LinkedListNode{`0})": {
+    "file": "System/Collections/Generic/LinkedList.Examples.cs",
+    "method": "AddNodes",
+    "title": "Adding nodes to a LinkedList"
+  },
+  "M:System.Collections.Generic.LinkedList`1.AddAfter(System.Collections.Generic.LinkedListNode{`0},`0)": {
+    "file": "System/Collections/Generic/LinkedList.Examples.cs",
+    "method": "AddNodes",
+    "title": "Adding nodes to a LinkedList"
+  },
+  "M:System.Collections.Generic.LinkedList`1.AddAfter(System.Collections.Generic.LinkedListNode{`0},System.Collections.Generic.LinkedListNode{`0})": {
+    "file": "System/Collections/Generic/LinkedList.Examples.cs",
+    "method": "AddNodes",
+    "title": "Adding nodes to a LinkedList"
+  },
+  "M:System.Collections.Generic.LinkedList`1.AddBefore(System.Collections.Generic.LinkedListNode{`0},`0)": {
+    "file": "System/Collections/Generic/LinkedList.Examples.cs",
+    "method": "AddNodes",
+    "title": "Adding nodes to a LinkedList"
+  },
+  "M:System.Collections.Generic.LinkedList`1.AddBefore(System.Collections.Generic.LinkedListNode{`0},System.Collections.Generic.LinkedListNode{`0})": {
+    "file": "System/Collections/Generic/LinkedList.Examples.cs",
+    "method": "AddNodes",
+    "title": "Adding nodes to a LinkedList"
+  },
+  "M:System.Collections.Generic.LinkedList`1.Remove(`0)": {
+    "file": "System/Collections/Generic/LinkedList.Examples.cs",
+    "method": "RemoveNodes",
+    "title": "Removing nodes from a LinkedList"
+  },
+  "M:System.Collections.Generic.LinkedList`1.Remove(System.Collections.Generic.LinkedListNode{`0})": {
+    "file": "System/Collections/Generic/LinkedList.Examples.cs",
+    "method": "RemoveNodes",
+    "title": "Removing nodes from a LinkedList"
+  },
+  "M:System.Collections.Generic.LinkedList`1.RemoveFirst": {
+    "file": "System/Collections/Generic/LinkedList.Examples.cs",
+    "method": "RemoveNodes",
+    "title": "Removing nodes from a LinkedList"
+  },
+  "M:System.Collections.Generic.LinkedList`1.RemoveLast": {
+    "file": "System/Collections/Generic/LinkedList.Examples.cs",
+    "method": "RemoveNodes",
+    "title": "Removing nodes from a LinkedList"
+  },
+  "M:System.Collections.Generic.LinkedList`1.Clear": {
+    "file": "System/Collections/Generic/LinkedList.Examples.cs",
+    "method": "RemoveNodes",
+    "title": "Removing nodes from a LinkedList"
+  },
+  "M:System.Collections.Generic.LinkedList`1.Find(`0)": {
+    "file": "System/Collections/Generic/LinkedList.Examples.cs",
+    "method": "FindNodes",
+    "title": "Finding nodes in a LinkedList",
+    "primary": true
+  },
+  "M:System.Collections.Generic.LinkedList`1.FindLast(`0)": {
+    "file": "System/Collections/Generic/LinkedList.Examples.cs",
+    "method": "FindNodes",
+    "title": "Finding nodes in a LinkedList"
+  },
+  "M:System.Collections.Generic.LinkedList`1.Contains(`0)": {
+    "file": "System/Collections/Generic/LinkedList.Examples.cs",
+    "method": "FindNodes",
+    "title": "Finding nodes in a LinkedList"
+  },
+  "P:System.Collections.Generic.LinkedList`1.First": {
+    "file": "System/Collections/Generic/LinkedList.Examples.cs",
+    "method": "NavigateNodes",
+    "title": "Navigating LinkedListNode properties",
+    "primary": true
+  },
+  "P:System.Collections.Generic.LinkedList`1.Last": {
+    "file": "System/Collections/Generic/LinkedList.Examples.cs",
+    "method": "NavigateNodes",
+    "title": "Navigating LinkedListNode properties"
+  },
+  "P:System.Collections.Generic.LinkedList`1.Count": {
+    "file": "System/Collections/Generic/LinkedList.Examples.cs",
+    "method": "NavigateNodes",
+    "title": "Navigating LinkedListNode properties"
+  },
+  "M:System.Collections.Generic.LinkedList`1.CopyTo(`0[],System.Int32)": {
+    "file": "System/Collections/Generic/LinkedList.Examples.cs",
+    "method": "CopyToArray",
+    "title": "Copying a LinkedList to an array"
+  },
+  "M:System.Collections.Generic.LinkedList`1.GetEnumerator": {
+    "file": "System/Collections/Generic/LinkedList.Examples.cs",
+    "method": "AddNodes",
+    "title": "Adding nodes to a LinkedList"
+  },
+  "T:System.Collections.Generic.LinkedListNode`1": {
+    "file": "System/Collections/Generic/LinkedList.Examples.cs",
+    "method": "NavigateNodes",
+    "title": "Navigating LinkedListNode properties"
+  },
+  "M:System.Collections.Generic.LinkedListNode`1.#ctor(`0)": {
+    "file": "System/Collections/Generic/LinkedList.Examples.cs",
+    "method": "NavigateNodes",
+    "title": "Navigating LinkedListNode properties"
+  },
+  "P:System.Collections.Generic.LinkedListNode`1.Value": {
+    "file": "System/Collections/Generic/LinkedList.Examples.cs",
+    "method": "NavigateNodes",
+    "title": "Navigating LinkedListNode properties"
+  },
+  "P:System.Collections.Generic.LinkedListNode`1.Next": {
+    "file": "System/Collections/Generic/LinkedList.Examples.cs",
+    "method": "NavigateNodes",
+    "title": "Navigating LinkedListNode properties"
+  },
+  "P:System.Collections.Generic.LinkedListNode`1.Previous": {
+    "file": "System/Collections/Generic/LinkedList.Examples.cs",
+    "method": "NavigateNodes",
+    "title": "Navigating LinkedListNode properties"
+  },
+  "P:System.Collections.Generic.LinkedListNode`1.List": {
+    "file": "System/Collections/Generic/LinkedList.Examples.cs",
+    "method": "NavigateNodes",
+    "title": "Navigating LinkedListNode properties"
+  },
+  "P:System.Collections.Generic.LinkedListNode`1.ValueRef": {
+    "file": "System/Collections/Generic/LinkedList.Examples.cs",
+    "method": "NavigateNodes",
+    "title": "Navigating LinkedListNode properties"
+  }
+}