dotnet/roslyn

AssemblyMetadata and ModuleMetadata's CreateFromStream apis need better documentation?

Open

#6,163 opened on Oct 19, 2015

View on GitHub
 (0 comments) (0 reactions) (0 assignees)C# (20,414 stars) (4,257 forks)batch import
Area-CompilersDocumentationhelp wanted

Description

public static AssemblyMetadata CreateFromStream(Stream peStream, bool leaveOpen = false);
public static AssemblyMetadata CreateFromStream(Stream peStream, System.Reflection.PortableExecutable.PEStreamOptions options);

In the overload that takes a bool with a default value of false, it is unclear what the api does when the bool is true. particularly, it is unclear when the stream should be disposed - can it be disposed asap versus should it be kept alive until the metadata is alive.

My inference was that if one wants to handle disposing the stream themselves (sooner or later), they are better served by using the second overload (to prefetch metadata or the entire image) than using the first. Is that correct?

Also, PEStream options has an option to leave the stream open, so why is the boolean overload required?

Similar questions arise for ModuleMetadata.CreateFromStream apis.

Perhaps there is a reason to all this, but I feel more detailed documentation will be helpful here.

Contributor guide

Tech stack
csharp
Domain
documentation
Issue type
documentation
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
2
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
1-3 hours
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
stale
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
clear
Prerequisites
C#Roslyn APIs
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
70
Research direction
The issue requests better documentation for the `CreateFromStream` methods in `AssemblyMetadata` and `ModuleMetadata`. To address this, add XML doc comments explaining the behavior of the `leaveOpen` parameter in the boolean overload, including when the stream may be disposed. Also clarify the differences between the two overloads and why the boolean overload exists alongside the `PEStreamOptions` version. Refer to the existing API source files in the Roslyn repository, such as `AssemblyMetadata.cs` and `ModuleMetadata.cs`, to understand the current implementation and ensure accurate documentation.
AssemblyMetadata and ModuleMetadata's CreateFromStream apis need better documentation? · dotnet/roslyn#6163 | Good First Issue