Refer to another section in C# XML documentation comments - c#

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

Related

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.

C# XML language file

I want to have my ASP C# application to be multi-language. I was planned to do this with a XML file. The thing is, i don't have any experience with this. I mean how, do i start? Is it a good idea to store the languages in an xml file? And how in the code do i set the values for ie my menu buttons? I'd like to work with XML because i never worked before with XML, i want to learn how to deal with cases like this.
You want to look into RESX resource files. These are XML files that can contain texts (and images) and they have standardized handling of localization/translations.
Support for this is built right into ASP.NET. There is a guide for how to use it and set it up at: http://msdn.microsoft.com/en-us/library/fw69ke6f(VS.80).aspx.
The walkthough is pretty detailed and should help you to understand the concepts. My preferred is method described a bit down in the document in the section "Explicit Localization with ASP.NET". Using this you will get a set of XML files with your texts and translations in a fully standardized format.
Do you know about the .Net From automatic translatation (based on .resx) resources ?
You're in luck, this sort of stuff is built directly into .Net
The way it's done is that for every page you have a language specific resx file.
eg
Homepage.aspx
Homepage.aspx.cs
Homepage.aspx.en.resx
Homepage.aspx.fr.resx
you simply dynamically figure out what resource file to use, and all the appropriate labels come through in French for example.
Helpful Tutorials and Videos
A Simple Example
Good luck.
If internationalization in .net is something you want to get into seriously, you might want to consider this
(and no - I have no stake in it)

Categories