dotnet-api-docs icon indicating copy to clipboard operation
dotnet-api-docs copied to clipboard

`Stream.Length` docs ambiguous

Open Smaug123 opened this issue 1 year ago • 3 comments

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"?

Smaug123 avatar Jun 27 '24 18:06 Smaug123

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.

ghost avatar Jun 27 '24 18:06 ghost

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.

ghost avatar Jun 27 '24 18:06 ghost

Tagging subscribers to this area: @dotnet/area-system-io