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...
Related
I'm currently documenting my C# code and would find it useful to include a code block that directly shows how a piece of code should be called. I use the <code> tag that is embedded into the summary:
While this works in general, I would like to preserve white space (line breaks, indentation). I tried the following so far:
I applied the xml:space="preserve" attribute to the <code> tag, but this had no effect at all.
I used <br /> to indicate individual new lines (this works as of VS 2019), but I can't insert spaces or tabs. I tried to use (for space) and (for tab), but the popup wouldn't show those.
I tried to use a CDATA section, but the code in between wasn't shown at all.
Is there any way to preserve white space in code tags of C# XML comments? Thank you for your help in advance.
Your first XML doc comment is correct. You shouldn't rely on what Intellisense shows you in the tooltips. Intellisense doesn't respect all formatting but it's getting better with each release of VS.
The newlines and whitespaces in a <code> tag are respected by tools that generate documentation out of the XML comments, such as VSdocman (I am the author) or Sandcastle. The same applies to CDATA. So if you generate, for example, an HTML documentation from your comments, your code block will look fine, with all whitespaces and newlines.
If you want to see it correctly also in Intellisense, you have to wait, or even better, send a feedback from Visual Studio to the MS team.
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.
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.
Does anyone know whether it is possible to refer to another section from the text of another one, e.g. to the ‘returns’ section from the ‘summary’ section or vice versa (within the documentation of a given method) and have a hyperlink generated by the compiler? (My original problem was how to refer to the return value from within the ‘summary’, as is already possible for parameters with ‘paramref’ or other members/classes etc. with ‘cref’. Then I realised that this problem is just a special case of the more general one described in my question).
There is no such possibility. Only paramref and typeref.
Maybe you need your own xml comments processor with custom tags. Or try to search about extensibility with custom tags using other tools.
For example NDoc (or maybe sandcastle has also extensibility points, but anyway for sandcastle source code is open):
http://ndoc.sourceforge.net/usersguide.html
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.