Document dotnet-gcdump tool

[Youssef1313]

Fixes #18935

Information source.

Internal review link.

[tdykstra]

This is a good start -- I had a few doc structure and wording suggestions. I would put this in the TOC following dotnet-dump

[tdykstra]

Following the pattern of https://raw.githubusercontent.com/dotnet/docs/master/docs/core/diagnostics/dotnet-counters.md we should have an Examples h3 section following each Options h3 section.

[tdykstra]

If this is the only option, what's the difference between specifying it an omitting it?

[Youssef1313]

@tdykstra, I had this question myself. It looks like there shouldn't be a difference. Perhaps the tool team might be planning to add other options later?

[sdmaclea]

/cc @josalem

[josalem]

This is only report type available right now and therefore the default, but we created this flag for future use if/when we add more report types.

[Youssef1313]

The options here are in the same order produced by the CLI help, do you want me to order them alphabetically as done with dotnet-trace? @tdykstra

---

The PR still lacks examples. I'll try adding some.

[tdykstra]

The options here are in the same order produced by the CLI help, do you want me to order them alphabetically as done with dotnet-trace?

There's no reason the docs have to follow the CLI help order; any way we can make the docs more usable seems worth doing to me. In this case the small number of options makes the benefit of limited value, but my preference is to be consistent.

[tdykstra]

It doesn't look like the description section incorporates the info from https://github.com/dotnet/diagnostics/blob/f63dc82eb4d92b8e057f7e3b5855cdf06f985f8c/documentation/dotnet-gcdump-instructions.md#known-caveats and https://github.com/dotnet/diagnostics/blob/f63dc82eb4d92b8e057f7e3b5855cdf06f985f8c/documentation/dotnet-gcdump-instructions.md#viewing-the-gcdump-captured-from-dotnet-gcdump -- is that deliberate?

[Youssef1313]

deliberate

I'll add these. Thanks for noticing this.

[josalem]

This is only report type available right now and therefore the default, but we created this flag for future use if/when we add more report types.

[adegeo]

@tdykstra Is this good to go or do you have other concerns?

[tdykstra]

A couple suggestions

[tdykstra]

This might fit as an H3 in the Description section

[tdykstra]

There's still a markdownlint error - we can merge this when that's resolved.

The PR still lacks examples. I'll try adding some.

You can save that for a later PR if you prefer.

[Youssef1313]

There's still a markdownlint error - we can merge this when that's resolved.

The PR still lacks examples. I'll try adding some.

You can save that for a later PR if you prefer.

I completely forgot about that. If it's okay to merge this, I'll open an issue to track adding examples. Otherwise, I'll find time to add them tomorrow or so.

[tdykstra]

Yes OK to merge and add later. Thanks for creating this doc!