XML docs for LINQ Join, LeftJoin, RightJoin #111177
Conversation
|
Tagging subscribers to this area: @dotnet/area-system-linq |
src/libraries/System.Linq.Queryable/src/System/Linq/Queryable.cs
Outdated
Show resolved
Hide resolved
| /// The following code example demonstrates how to use <see cref="Join{TOuter, TInner, TKey, TResult}(IQueryable{TOuter}, IEnumerable{TInner}, Expression{Func{TOuter, TKey}}, Expression{Func{TInner, TKey}}, Expression{Func{TOuter, TInner, TResult}})" /> to perform an inner join of two sequences based on a common key. | ||
| /// </para> | ||
| /// <code> | ||
| /// class Person |
There was a problem hiding this comment.
@carlossanlop @gewarren I don't think I've seen us use <code> blocks in dotnet/runtime source code before. Does the porting tool handle them correctly or should the code samples by added to dotnet-api-docs in a different way?
There was a problem hiding this comment.
This should work. Even better is to add a language tag: https://learn.microsoft.com/en-us/contribute/content/dotnet/api-documentation#language-attributes.
You can also consider putting these examples in separate files since they take up quite a few lines. I'm not exactly sure on the plumbing, but the dotnet/machinelearning repo uses separate code files: https://github.com/dotnet/machinelearning/blob/886e2ff125c0060f5a251056c7eb2a7d28738984/src/Microsoft.ML.TensorFlow/TensorflowCatalog.cs#L32.
The code files actually live in the dotnet/machinelearning repo too: https://github.com/dotnet/machinelearning/blob/main/docs/samples/Microsoft.ML.Samples/Dynamic/TensorFlow/TextClassification.cs. But I believe the URL looks the way it does (~/../docs/samples/docs/samples/Microsoft.ML.Samples/Dynamic/TensorFlow/TextClassification.cs) to make it work on learn.microsoft.com, and I'm not sure if this would work in IntelliSense, or if that even matters since I don't think examples are shown. The docs repo hooks up the URL root /docs/samples here.
Lengthy remarks can also go in separate files. You can see an example of that in this repo.
There was a problem hiding this comment.
Thanks, all the above makes sense to me... One thing I'm unsure about, is whether remarks referenced in a separate file are shown in Intellisense - unless I'm mistaken, contrary to examples these are shown in VS etc and we don't want to lose that?
In any case, I'm fine with doing whatever here, but it seems like this is the first time we're discussing these questions on the runtime repo :) Should we have some clear guidance on how want this to look, e.g. where the referenced example/remarks files are supposed to live etc.?
See #110872 (comment)