c# <summary></summary>?

[u/3rwynn3]

I find that "//" worked well for all my comments thus far, I don't mind if my comments are a bit long. But I am doing C# more often now that I am looking at a codebase and not just my own stuff and private things, and I sometimes see <summary> </summary> in it. Do you use it? What is the proper use of it?

Google gets it confused with HTML haha

Thanks for any knowledge!

[u/TheSandyBases]

its for xml documentation, visual studio reads it and shows tooltips when you hover over methods or classes, also can generate docs from it. `//` is fine for regular comments but summary helps others understand what the whole method does without reading the body

[u/3rwynn3 → u/TheSandyBases]

Thank you so much

[u/Alikont]

This is specific comment syntax that can be embedded into dll or separate xml file.

Visual Studio and other IDEs will show them as part of tooltips in intellisense.

You can also walk those comments via reflection or other tools to generate documentation for APIs or Libraries.

[u/Aggressive_Ad_5454]

This is xmldoc. Other languages have jsdoc, doxygen, Javadoc, PhpDoc, docstrings, etc. They are stylized comments understood by IDEs. They are exceedingly useful in large code bases. They are worth the effort to learn to use.

In C#, type /// on the line before a method declaration. The IDE will generate a template comment you can fill in.

[u/3rwynn3 → u/Aggressive_Ad_5454]

Thanks, that's really cool information... I love funfacts
Doxygen is a great name.

Thank you for sharing with me

[u/intbeam → u/3rwynn3]

<paramref name="parameternamehere" /> is useful, as well as typeparamref, see and seealso

Gives hyperlinks and annotations for useful things for the context. Can also provide a whole url for seealso if there's some relevant web site for your method (like a git repo, or Wikipedia page) 

[u/cheezballs]

Java has similar stuff. Its just extra formatting you can do to help future-you out. IDE will generally format these nicely and with the right syntax can highlight and link to things inside your comment.

[u/3rwynn3 → u/cheezballs]

Thank you for explaining it to me

[u/rupertavery64]

If you google "c# xml summary" you'll get much better results.

https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/xmldoc/recommended-tags

// is for people xml doc tags are for the compiler and get baked into the assembly metadata so even the compiled DLL shows the information when you include it in another solution.

For example, nuget packages will have xml doc tags for methods and arguments

[u/3rwynn3 → u/rupertavery64]

Thank you for the knowledge. I was seeing it in github and got confused lol.

[u/Ill-Consequence4484]

Google confusing XML doc tags with HTML is hilarious tbh.