search

dotnet / dotnet-api-docs

.NET API reference documentation (.NET 5+, .NET Core, .NET Framework)
https://docs.microsoft.com/dotnet/api/
Other
679 stars 1.52k forks source link

`Stream.Length` docs ambiguous #10069

Open Smaug123 opened 5 days ago

Smaug123 commented 5 days ago

The docs for Stream.Length currently say:

When overridden in a derived class, gets the length in bytes of the stream.

This is ambiguous, in the sense that I felt the need to spin up dotnet fsi to confirm to myself that I had picked the correct interpretation. Does it mean "the remaining length", or "the absolute length"? Of course it means "absolute", and most people will probably choose that interpretation anyway, but in a scenario where the Stream represents "forgetting everything that came before", it may be natural to interpret it as "remaining" (because the Stream has forgotten its past!).

I don't have a great suggestion for an improvement, but perhaps a remark to the effect that "in a stream which supports Seek, this is expected essentially to be the value of Position after Seek(0L, SeekOrigin.End)"? (Position is much more natually an absolute concept, because you can Seek backwards.) Or perhaps "When overridden… gets the total length in bytes of the stream"?

dotnet-issue-labeler[bot] commented 5 days ago

I couldn't figure out the best area label to add to this issue. If you have write-permissions please help me learn by adding exactly one area label.

dotnet-issue-labeler[bot] commented 5 days ago

I couldn't figure out the best area label to add to this issue. If you have write-permissions please help me learn by adding exactly one area label.