Learn C#: Documenting your code

[tdykstra]

Issue tracking new topic at https:/dotnet/core-docs/blob/master/docs/languages/csharp/codedoc.md

[shmuelie]

I'd like to work on this. Any guides/things I should look at?

[mairaw]

@BillWagner is this something you can help @SamuelEnglard with?

[BillWagner]

@mairaw Yes.

@SamuelEnglard Start here: https:/dotnet/core-docs/blob/master/CONTRIBUTING.md and just @ message me if you have any questions.

[shmuelie]

I've started! https:/SamuelEnglard/core-docs/blob/doc-code/docs/languages/csharp/codedoc.md

[shmuelie]

Posting Questions I asked @BillWagner on Twitter here:

Q: I'm using msdn.microsoft.com/en-us/library/… for comment conventions. Is there an updated one I should look at instead?
A: That looks correct.

Q: For XML comments, can/should I include tags that are none standard but used by sandcastle?
A: I would stick with the standard tags.

[mairaw]

Great @SamuelEnglard.

Can you give an example of what are non-standard tags that are used in Sandcastle @SamuelEnglard? I agree with @BillWagner on his answers but would like to know what were those tags.

[shmuelie]

These are one's I've personally used for example.

This element is used to list events that can be raised by a type's member.
<event cref="eventType">description</event>

This element is used to indicate that a particular type or member is preliminary and is subject to change.
<preliminary /> or <preliminary>description</preliminary>

This element is used to indicate whether or not a class or structure's static and instance members are safe for use in multi-threaded scenarios.
<threadsafety static="true | false" instance="true | false" />

This element is used to create a note-like section within a topic to draw attention to some important information.
<note type="noteType">note content</note>

This element is used to create an inline link an external website within the text in which it occurs.
<see href="url" [target="_blank | _self | _parent | _top"] [alt="alternate text"] /> or <see href="url" [target="_blank | _self | _parent | _top"] [alt="alternate text"]>inner text</see>

This element is used to apply language-specific formatting to a limited set of keywords.
<see langword="null | Nothing | nullptr | static | shared | virtual | Overridable | true | True | false | False | abstract | MustInherit | sealed | NotInheritable | async | await | async/await | Async | Await | Async/Await | let! | async/let!" />

[mairaw]

Thanks @SamuelEnglard for this list. From a recent exercise with the dev team, I know they wanted us to use the <see langword> in our /// comments and VS actually colorizes the word differently. But <see href> didn't work as expected when generating xml documentation from the code.
I'd start with the basic recommended ones for now and I'll see if there's any plan to add support these keywords later on. I need to find the right contact for that.

[shmuelie]

@mairaw of those I admit <see langword> is my favorite. And my coworkers can tell you I go nuts on XML comments.

I'll stick to the basic ones for now. Simple enough. Thanks!

[BillWagner]

@SamuelEnglard I don't know of any plans to extend the C# spec for new XML elements in doc comments.

/cc @MadsTorgersen

Should a discussion of new XML Comment grammar move to the Roslyn repo?

[shmuelie]

@BillWagner I don't know of any either (though I admit I suspect you keep a close ear on these things than I do).

My reasoning for wanting to add them is that they are useful and are understood by tooling (even VS)

[BillWagner]

@SamuelEnglard This has been stale for a long time. I'm closing it. We have coverage on this topic, but I know you were adding new information here.

If you have work toward it that you want us to publish, you can re-open it and let me know.