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.
Related
I wrote a C# routine to look at GitHub repository sites using the Microsoft webclient class, and then added GitLab.
I started out with the https://gitlab.com/gitlab-org/ repository collection.
GitHub works fine; but the GitLab site uses "<!---->" comment items in their HTML coding. The webclient does not parse this correctly; saving the web page has missing content.
Is this an invalid coding by GitLab or does webclient have a bug? The usual browsers (Firefox and Chrome) parse the page properly, but they may do so even though it is invalid coding maybe.
<!--: Signifies the beginning of an HTML comment.
-->: Signifies the end of an HTML comment
These are included in the HTML markup specifications and are valid. However, they should not be included in the UI representation of the page, nor should any content between.
Technically, <!----> is valid.
The specifications can be found here:
https://www.w3.org/TR/html5/syntax.html#comments
XML comments follow similar guidelines: https://www.w3.org/TR/REC-xml/#sec-comments
Not only this is a valid comment, but GitLab 15.7 (December 2022) propose to better preserve said comments:
HTML comment support in the Content Editor
When you collaborate on a wiki page or blog post, you often come across inline HTML comments that are not meant to be rendered.
Previously, the Content Editor would ignore these comments to reflect what the actual content would look like.
The problem, however, was that making edits in the Content Editor could unexpectedly remove these comments from the file.
With this release, you can insert new HTML comments inline and edit comments already on the page.
These comments appear in a way that indicates they won’t be rendered.
This feature can help you manage longer wiki pages and is an important step towards editing issue descriptions and comments in future releases.
See Documentation and Issue.
I have a localized app with all strings in Resources.resx file. This is one of the many approaches which is really designed for WinForms, but works with WPF as well.
The problem is when I want to put a non-breaking space in localized text. Entity code is converted to text. Inacceptable. So I tried to paste the Unicode character in the text, but it looks like it's converted to regular space and doesn't really work.
Of course I'm open to change localization of my app, but it's really important it should work automatically - the language should be derived from system display language. This is the main reason I use Resource Designer for it. If I could use resource dictionary and still use automatic detection feature I would switch to resource dictionary.
When I copied non-breaking space character from Word or any website, it didn't work, so I thought it's no way to do this.
Then I finally got the idea of inserting into a XAML TextBox, copy it from there and paste inside resource designer text.
Not a great solution, but it works. It can be sort of automated with keeping non-breaking space sample in any text file within the project. Just to copy it from there if needed. The greatest downside of this is the space totally looks like a normal space, so I won't be able to see what kind of space is in the text until I actually display it in a control.
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...
When I set the Title Tag of a page in ASP.NET, it adds carriage returns which is unneccessary, is there any way in .NET to remove the carriage returns. It happens when I create a new website, not just the site I've been developing.
<title>
The Title of the Page
</title>
Should really be
<title>The Title of the Page</title>
Viagogo.com kind of gets rid of the first carriage return, not the second so there must be a way. If it needs a coding solution, C# would be preferred.
This has really nothing to do with .net.
It's a document formatting thing, and differs from IDE to IDE. Often helper software such as resharper formats a document according to a set of rules and standards, making documents easier for others to read.
Most IDEs lets you edit the way you want this to be automatically generated, if you want any at all.
Also, see the following SO post for a similar issue.
I found http://www.hanselman.com/blog/MovingViewStateToTheBottomOfThePage.aspx which I amended to minify and remove the line breaks from the title tag by adding in replace statements to remove the line breaks.
I'm working with doxygen and has encountered an issue, where the <code> in C# code documentation is interpreted differently that the \code command for doxy. Both seems to be interpreted as code, and both are typed in monospace fonts. But the \code encapsulates the code in a nice box and understands newline, while code in <code> is just printed out in one line with no box.
Is it possible to make doxy interpret <code> as \code?
Or before it interprets the documentation change the <code> to \code and </code> to \endcode to work around the problem?
I am aware I could just have \code and \endcode statements in the documented code segments, but I work with other tools like Resharper that interprets <code>, and will not understand \code. Having the code documentation as close the standard (http://msdn.microsoft.com/en-us/library/5ast78ax.aspx) makes it easier to work with different tools.
The 1.8.2 version of doxygen has now fixed this error and the code tag is working as it should.