Docs: Code Snippets to Accompany Class Member Documentation

[mitevpi]

Would it be possible to add brief code snippets underneath key methods/properties in order to quickly communicate usage/use cases?

I'd love to contribute if that's something that would be useful to others as well.

ex: In the case of the ColumnAttribute.Ordinal Property, if there was a "Code Sample" section right above/below the "Applies To" header, I think that would be very clear and helpful. The sample could be something as simple as what already exists in some of the tutorials/intros:

// Brief explanation, ex:
// Data is loaded without headers/labels, and the ColumnAttribute.Ordinal Property
// is used to define the identity of different data elements (columns) based on index.
public class TaxiTrip
{
    [Column(ordinal: "0")]
    public string vendor_id;
    [Column(ordinal: "1")]
    public string rate_code;
}

---

Document Details

⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.

• ID: 8d2663c1-ff59-7fa8-0fa4-c85c3099974e
• Version Independent ID: ef149bec-3b58-b29a-d71e-7a786ef27ac7
• Content: ColumnAttribute Class (Microsoft.ML.Runtime.Api)
• Content Source: dotnet/xml/Microsoft.ML.Runtime.Api/ColumnAttribute.xml
• GitHub Login: @dotnet-bot

[mairaw]

@asthana86 @aditidugar @JRAlexander FYI on samples request for ML.NET API docs

@dend for content that is auto-generated from /// comments, is it possible to add remarks and examples without losing them when docs get regenerated?

[mitevpi]

Would something like the example tag work?

[mairaw]

Yes, this works @mitevpi but I'm wondering if we really wanna embed examples to APIs like that.

[pkulikov]

@mairaw can it be done the similar way as it's done now for .NET API?

[mairaw]

@pkulikov .NET is kind of a special case because we can't auto-generate docs from source as other products can for a variety of reasons. So, for ML.NET we'd be following the same pattern that all others teams are using for reference docs including ASP.NET Core. I just need to learn now how to handle those (I think other teams are not really adding samples at the moment to the reference docs) considering some of the changes that the engineering team is planning for reference docs.

[pkulikov]

@mairaw thank you very much for the reply as that makes things clearer to me. Then I have two follow-up questions:

• As the docs are auto-generated, there is no reason (for contributors not from the docs and engineering teams) to make PRs to the dotnet/ml-api-docs repository?
• If I want to fix a typo (dotnet/ml-api-docs#21), then I should fix it by PR in the dotnet/machinelearning repository?

Given that, the Edit buttons on the pages with ML.NET API look to be not useful, because clicking them results in a PR to dotnet/ml-api-docs repository

[mairaw]

@pkulikov

As the docs are auto-generated, there is no reason (for contributors not from the docs and engineering teams) to make PRs to the dotnet/ml-api-docs repository?

Correct! @dend are we working on enabling folks to go directly to source when API docs are auto-generated?

If I want to fix a typo (dotnet/ml-api-docs#21), then I should fix it by PR in the dotnet/machinelearning repository?

Correct. (Sorry I missed that PR)

Let me learn how this works and I'll remove the Edit button from those docs if they're not useful.

[mairaw]

Assigning this issue to myself to investigate next sprint.

[mairaw]

Moving this to the backlog. We need to sit down with @dend and understand how this works for auto-generated content.

[mairaw]

FYI @sfilipi. I believe you're already working on adding code samples, correct?

[mairaw]

Closing since this API no longer exists. /cc @natke