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.

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

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

Solution 3

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.

Solution 4

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.

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

View more solutions

Comments

[Jamiec]

Its not the comments you need to wonder about - any valid XML is acceptable in them - its whatever is parsing the resultant XML you need to wonder about, that is what will allow some formatting markup.

[Patrick Hofman]

Then you still need to escape it, since it should be valid XML content.

[Rich]

@PatrickHofman: I'm fairly certain that <summary>Some <strong>bold</strong> text</summary> is valid XML. No need for escaping.

[Patrick Hofman]

Sorry, you are right. I was just thinking of using < in the comments, which isn't allowed. Those need to be escaped, and these probably too to end up correctly.

[Patrick Hofman]

Joey, would you mind to give ReSharper a try with <strong>?

[Rich]

No change, as it explicitly tells that it's just the literal < and > characters. XML documentation, unlike Javadoc, carries no connotation that the output is HTML. Thus it isn't in this case. Java IDEs usually present Javadoc with rendering HTML, but that's to be expected.

[miroxlav]

Are no plugins needed for that? Was it already possible in Visual Studio 2015?

[Antoni]

Sorry @miroxlav, I didn't mean to say Visual Studio will understand wiki markup. That would only be a convention.

[miroxlav]

Thanks, yes, but if I want to add text "returns value depending on ReadAllFiles and PreserveTimestamp settings", these ways of emphasis are of little use, they would make the text less readable.

[Admin]

So very few people write proper documentation for other programmers. What you are doing is admirable.