C# tutorials - xml documentation

[stevehoag]

Show how to document code using XML doc comments.

Tutorials should include one or more code examples, each example should also show expected output and should include an explanation of the code where it isn't obvious. Examples shouldn't be dependent on a specific IDE or target platform.

[tonerdo]

@BillWagner this looks interesting. I'd like to work on this

[BillWagner]

@tsolarin That sounds great.

Can you and @samuelengland keep in touch as your working? He's working on issue #494, which is related. I will keep an eye on both of your branches and answer any questions.

I'll leave this issue assigned to me (as we can't assign issues to non-team members). That will make sure no one else grabs it.

[tonerdo]

@BillWagner that's fine, here's my branch https://github.com/tsolarin/core-docs/blob/xml-doc/docs/csharp/codedoc.md

[BillWagner]

@tsolarin I like the start. I'd like to see samples of each of the tags to help people understand how to use each.

[tonerdo]

@BillWagner definitely, was just getting started, will surely include syntax examples and possible attributes

[tonerdo]

@BillWagner my first draft is complete, have a look: https://github.com/tsolarin/core-docs/blob/xml-doc/docs/csharp/codedoc.md

[tonerdo]

/cc @BillWagner

[BillWagner]

@tsolarin This is a great start.

You've covered all the main tags, and done so quite well.

I have two (related) recommendations for your next draft.

I would order the tags in a logical order of their use rather than alphabetically. I think this applies both to the list and the sections below. I'd likely start with

and then . After that, there are a lot of directions you could go, so I'll leave it up to you. I'd expect and to be next to each other though.

After that, make a Pull Request, and we'll do a more detailed content review and then merge.

Thanks again for helping and contributing.

[tonerdo]

@BillWagner so in your last comment I assume you made reference to some tags, they're not HTML tags so they don't show up.

[BillWagner]

@tsolarin I'm sorry I didn't explain myself well. I meant that you covered all the XML tags that C# uses.

What I meant by 'ordering the tags' would be to re-order the sections covering each XML tags that C# understands to use the order a reader would want to use them, rather than alphabetically.

I hope that helps.