C# Comment Template - c#

Would anyone happen to know if you can make a custom template for comments in c#? I use a modification of the RME style of commenting instead of the section. Unfortunately, I don't have a ghost doc pro subscription.
I would like it to work just like visual studio where I type '///' and it creates the template of the comment. I have seen similar questions saying you can't do this but they date form 2010 and it seemed to be a highly requested feature.

I use snippets to create source file headers and a comment snippet to add a line comment to the bottom of the header.
I am sure you could make a snippet that inserts whatever you want after ///
Snippets allows you to enter information through input boxes you can set up but if you are looking for something equivalent to GhostDoc where it fills in everything for you, I don't think that functionality is there.

Related

In C# XML Documentation, only the summary tag is working

I'm trying to add XML documentation for my homework on VS code, but only text in the summary block shows up when hovering over the function/variable.
It also happened in the normal Visual Studio and on multiple computers, so I figure it's just something I don't understand, but I tried googling it and came up with nothing. I've also tried just straight up copy-pasting from a Microsoft article, but it still did not work
Yes, the intellisense only shows you the summary. It will never show you remarks or exceptions, but if you use it on a method, you will see the intellisense for each parameter as you enter them.

What are regions summary comments in C# source code?

I know what is attributes in C#, but I don't know what are those text. I never see them in any C# language textbook.
Can you help me explain what is the text in the code?
What are their purpose? Can I safely delete them?
///
#region
#region
lets you specify a block of code that you can expand or collapse when using the outlining feature of the Visual Studio Code Editor. In longer code files, it is convenient to be able to collapse or hide one or more regions so that you can focus on the part of the file that you are currently working on.
https://msdn.microsoft.com/en-us/library/9a1ybwek.aspx
/// comments
In Visual C# you can create documentation for your code by including XML elements in special comment fields (indicated by triple slashes) in the source code directly before the code block to which the comments refer.
When you compile with the /doc option, the compiler will search for all XML tags in the source code and create an XML documentation file. To create the final documentation based on the compiler-generated file, you can create a custom tool or use a tool such as Sandcastle.
Also, Visual Studio intellisense will use this information to show to the consumer of your public APIs as description. Like if you have descriptions about an input argument, the comments you mention for that argument will be displayed to the user trying to call that function in Visual Studio like the image below:
The cooments xmldocs comments. You can safely delete them, if you want to, of course.
Regions are text "helpers" which help you to specify outlining of your code.
/// is for auto-generated documentation
Yes, it's safe to delete. Microsoft documentation here.
#region and #endregion can be safely deleted if you delete just these tags (not the code in between)
Yes both can safely be deleted without any damage to the code, so long as you delete just the #region and #endregion tags and not the code between.
Regions are just what the name implies, a region of code that does a specific thing, for instance in many controllers you see a Create, Read, Update, and Delete region, to define where the code for CRUD operations goes, this also allows you to collapse a whole region in VS and likely other IDEs as well, to better view only what you want to see, makes navigating code easier.
Three slashes /// are used to define the XML documentation on classes, properties and methods. VS has the option to output this on a build to an XML document, then there are other tools that can be used to make that XML easier to use. The summary also shows up as the tooltip when you hover over usages of those classes, methods and properties in VS, to make it easier to understand the function of the methods and classes without reading over the code.
Neither is actually vital to the code, but they are helpful to developers that are looking at the code, even the same person who wrote the code can get use out of XML comments when coming back to something they did months ago.

Bold or italic in C# or VB documentation comments?

Is there a way to use bold or italic inside documentation comments? Something like:
/// <summary>Cleanup method. This is <b>recommended</b> way of cleanup.</summary>
public void CleanAll();
The list of predefined tags does not contain such a feature, but do you know of some way of achieving emphasis/highlighting? Preferably, if it could be shown also in tooltips when hovering over the code.
We have <c> and <code> there, but they already have their semantics.
This feature is now available in Visual Studio 2019 version 16.3.0 (release notes).
You can use the <i> or <em> tags for italic.
You can use the <b>or <strong> tags for bold.
From the release notes, a variety of html tags seem to be supported, but the official documentation doesn't seem to be updated with this new feature just yet.
It looks like this: .
OP's note: This was the accepted answer before 2019 Visual Studio update after which I accepted the other answer. This one is still useful and valid for users without that update.
Not strictly, no. However, Sandcastle (a documentation generator that generates HTML from the documentation) supports to just use HTML in there, so you can use <em> and <strong> just fine if you build it with Sandcastle.
To put it another way: As Jamiec already notes, XML documentation comments are just XML. So you can put any valid XML in there; the compiler will happily write that into the documentation XML file. It all depends on the software that processes that file. Sandcastle just passes anything it doesn't know on as HTML, since that's its output format anyway.
Visual Studio will simply ignore them when displaying the help tooltip:
ReSharper in its Ctrl+Q view will show HTML tags as text which makes things a bit ugly:
Those are usually only of concern to you if you author a library to be used by others, though. But it also means that within the IDE no one can see your emphasis as intended.
I have found actually little need for emphasis when writing API documentation; oftentimes you can write a sentence differently or restructure to have important nodes in a separate paragraph near the end, to not need emphasis at all. Consistent language and phrasing also helps readers to pick up important notes once they're used to it.
Your code probably just was an example, but I think the summary needs emphasis least of all since it only notes – in a short sentence – what a type is or a method does. If anything, use it in the remarks and even then I'd carefully consider whether you actually need it.
There are other ways of adding emphasis:
- Upper case: some BOLD text // you are shouting, but they WILL read it
- First letter: some Bold text // less emphasis
- Asterisks: some **bold** text // 2 asterisks seem to work best
- Dashes: some --bold-- text // less emphasis
Plain text is old-school, but it can be very effective - and works long after the technology has changed.
An alternate way is to use a wiki markup-like style instead.
/// <summary>Cleanup method. This is *recommended* way of cleanup.</summary>
public void CleanAll();
Edit 1:
AFAIK Visual Studio doesn't understand wiki markup. I was just suggesting to use wiki markup as a convention. Your team would still see the raw (unformatted) wiki markup in the method's intellisense.
To add clarification to the accepted answer above ('This feature is now available in Visual Studio 2019 version 16.3.0' https://stackoverflow.com/a/58227889/17203657)
From the Release Notes (https://learn.microsoft.com/en-us/visualstudio/releases/2019/release-notes-v16.3#net-productivity-163P1) 'There is now Quick Info style support for XML comments.'
Quick Info is when you hover over the method (it is NOT Intellisense), it DOES support Bold, Italic.
IntelliSense is what shows when you're adding arguments to the method, it does NOT support Bold, Italic.
As of VS 16.11.5 I've not found a way to add bolding or italics to the IntelliSense view.
Note: I do not have enough points to add this as a Comment.
I was trying to add a line break into the Intellisense display when I came across <see cref="YourReferenceHere"/> (see here), which inserts (according to the documentation) a clickable reference into the documentation. I have not figured out how to click on Intellisense tooltips, but it does provide a type-formatted/colored display which helps your reference to stand out (note that the reference must be available to Intellisense).
Side Note: I never did figure out how to do a single line break. Closest I can get is a double line break, using the <para/> tag...

// comments in doxygen

I have a c# project that I need to document with doxygen. It picks up the comments autogenerated by visual studio's /// but unfortunately it does not pick up on the normal // comments. Is there a config setting that I am missing? Or is this just not possible?
/// is referred to as XML Documentation Comments. This is how Doxygen and other documentation-generating software locate areas of the code you want to be used as documentation.
To elaborate, if you have comments like // This is hacky, but I'll return to it later in your code you should change them to an XML comment section on the method, property, or object in question.
To me this is not a bug but a feature. There are comments that I do want to leave in the code and not extract and show everyone. The distinction between the /// and the // allows me to do this.

In Visual Studio, is there a quick way to generate these types of comment blocks?

If anyone knows the name for these types of comments, if one exists, please modify my question.
I frequently see comment blocks such as this:
/**********************************************
* Some Important Text Here
**********************************************/
Sometimes they can look like this:
/**********************************************
********* Some Important Text Here *******
**********************************************/
I've also seen them prettier than that.
They seem useful for noting sections of code, and important messages, such as license blocks. But, I feel like there *must* be a "lazy" way of doing this in Visual Studio, or at least an addon, because typing them manually is a pain.
Thanks!
P.S. If this feature or a point-and-click way to do it doesn't exist, then I know what VS plugin I'm writing next.
create a code snippet for them
You could perhaps look at GhostDoc, it is great for writing neat, clean, consistent style commenting in your code. It uses XML markup, and can later be exported for documentation.
If you want fixed-text blocks, then add a Code Snippet for each one you need.
If you want auto-generated documentation blocks for absolutely any code element, then you might like to try my addin, AtomineerUtils. (Similar to GhostDoc, but with significantly more features, a much better documentation generation engine, better formatting control (e.g. word wrapping of comments and documentation comments) and support for many more programming languages and documentation block styles).
You could create a toolbar macro which inserts that text at your cursor position when you click on the toolbar icon.

Categories