docs: Add disposal warning to File.GetStream() (#1509)

[thomhurst]

Summary

• Adds XML documentation to File.GetStream() method warning that the caller is responsible for disposing the returned FileStream
• Includes code examples demonstrating proper usage with await using (async) and using (sync) patterns
• Prevents resource leaks by making disposal responsibility explicit in the API documentation

Fixes #1509

Test plan

• Verified build succeeds with dotnet build src/ModularPipelines/ModularPipelines.csproj -c Release
• Verify documentation renders correctly in IntelliSense

🤖 Generated with Claude Code

[thomhurst]

Summary

Adds comprehensive XML documentation to the GetStream() method, including disposal warnings and usage examples.

Critical Issues

Missing logging in GetStream() method (src/ModularPipelines/FileSystem/File.cs:64-67)

While this PR only adds documentation, I noticed the GetStream() method is missing the LogFileOperation() call that all other file operations in this class use. This is inconsistent with the established logging pattern.

Every other method (ReadAsync, WriteAsync, Create, Delete, MoveTo, CopyTo, etc.) includes logging, but GetStream does not.

Suggested fix:

public FileStream GetStream(FileAccess fileAccess = FileAccess.ReadWrite)
{
    LogFileOperation("Opening FileStream: {Path} [Module: {ModuleName}, Activity: {ActivityId}]", this);
    return System.IO.File.Open(Path, FileMode.OpenOrCreate, fileAccess);
}

This doesn't block the documentation change, but should be addressed separately or as part of this PR.

Suggestions

None - the documentation itself is well-written and follows best practices.

Verdict

✅ APPROVE - Documentation change is good, but please consider adding logging to GetStream() either in this PR or as a follow-up.

[Copilot]

Pull request overview

This PR adds comprehensive XML documentation to the File.GetStream() method to explicitly warn developers about their responsibility to dispose the returned FileStream. The documentation includes practical code examples demonstrating proper disposal patterns.

• Adds XML documentation with disposal warning
• Includes code examples for both async (await using) and sync (using) disposal patterns
• Prevents potential resource leaks by making API contract explicit