Bold or italic in C# or VB documentation comments?

Question

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.

Answer 1

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: .

Answer 2

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.

Answer 3

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.

Answer 4

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.

Answer 5

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...

Answer 6

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://docs.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.