[Doc] Reference FakeTimeProvider in xml comments to TimeProvider class.

[voroninp]

Background and motivation

Testability is a motivation for introduction of TimeProvider class, thus it would be benefitial for the developers to find out about extras from the documntation.

Curruntly there is no mentioning of FakeTimeProvider class in xmldoc.

API Proposal

I propose to add <remarks> section which will cotnain something like the following:

/// <summary>Provides an abstraction for time.</summary>
/// <remarks>Use FakeTimeProvider class from package Microsoft.Extensions.TimeProvider.Testing for convenient testing.</remarks>
public abstract class TimeProvider

API Usage

N/A

Alternative Designs

No response

Risks

If you ever change the name of the FakeTimeProvider or its package, documentation will become stale.

[colejohnson66]

This belongs in dotnet/dotnet-api-docs.

[voroninp]

@colejohnson66 , are you shure that tech writers are responsible for writing xmldoc comments? Or is it just how you organize issues?

[colejohnson66]

The XML doc comments are not what is shown on the documentation website. The website is generated from the dotnet/dotnet-api-docs repository.

[voroninp]

Yes, and I am speaking about adding the remark to xmldcos.

[tarekgh]

This should be fixed in https://github.com/dotnet/dotnet-api-docs/blob/main/xml/System/TimeProvider.xml.

[tarekgh]

@voroninp are you interested to submit a PR for that?

[voroninp]

@tarekgh , I am a bit confused, though. Are not those xmls just build artefacts?

[tarekgh]

The triple slashes Xml docs in source get ported first time to the dotnet-api-docs repo but I don't think any more changes in the source will get automatically ported to the public docs. So, to ensure the public doc https://github.com/dotnet/dotnet-api-docs/blob/main/xml/System/TimeProvider.xml is updated, just fix it there directly. You are welcome if you want to update the source triple slashes docs too.

CC @carlossanlop who knows is the expert in porting the triple slashes docs to dotnet-api-docs.

[voroninp]

@carlossanlop, could you add more clarity, please? Should I change it only in source code or in doctnet-api-docs as well?

[carlossanlop]

What Tarek said was correct. You can send the PR directly to dotnet-api-docs, specifically to modify this line: https://github.com/dotnet/dotnet-api-docs/blob/b3c5df35606c832755220d2fb40225a1d5014662/xml/System/TimeProvider.xml#L36 Making the change there ensures we ship the documentation to customers. Eventually, we will backport those texts to source code in dotnet/runtime, we currently don't have an automated process for that.

Now, if you really really really want to do the super awesome thing, you can additionally submit another PR to add the same suggested remark to the actual API in dotnet/runtime, but you can consider this optional: https://github.com/dotnet/runtime/blob/d40ac7c77266f6b7386e5922d3fd1c2a849ce97e/src/libraries/Common/src/System/TimeProvider.cs#L10-L11