xml-comments

.Net XML comment into API Documentation

Is there an easy way to produce MSDN-style documentation from the Visual Studio XML output? I'm not patient enough to set up a good xslt for it because I know I'm not the first person to cross this bridge. Also, I tried setting up sandcastle recently, but it really made my eyes cross. Either I was missing something important in the pr...

Add XML Comments to class properties generated by the LINQ to SQL designer

I used the LINQ to SQL designer in Visual Studio to create an object model of a database. Now, I want to add XML comments to each generated property but I can't figure out how to do it without erasing the properties the next time the dbml file is refreshed. How can this be done? ...

Generating Documentation from C# XML Comments

I've recently started a new project and I'm using C# for the first time. I've found that while Visual Studio is helpful in creating C#'s XML comments to document your classes and methods, there's not much you can do to generate MSDN or Javadoc style documentation. Google tells me that Visual Studio 2003 included a tool to generate such...

Tool to reformat xml-comments (Visual Studio 2008)

Hi there, does anyone know of a macro or add-on for VS 2008 which reformats xml-comments? There has been this really smart CommentReflower for the older version of VS, but I couldn't find a release supporting VS 2008. Any ideas? Thanks in advance! Matthias ...

VS: Attribute for ignoring missing XML comments when building

I have a VS2008 solution using xml documentation, and we have warnings as errors turned on for release mode (a nice feature IMHO); this results, however, in long lists of 'missing xml comment' errors for such things as every element of a (self describing) enum. Does anyone know of an attribute or similar which switches off the requremen...

Finding missing XML comments content with Visual Studio.

Throughout or C# sourcecode we have a lot of comments that miss the actual content such like this: /// <summary> /// </summary> or this: /// <summary> /// /// </summary> or this: /// <param Name="flag"></param> Unfortunately Visual Studio does not generate warnings for this type of missing comments. But for us it would be nice i...

Framework goto definition shows comments, are these generated from xml comments?

I was mildly surprised recently to discover that my carefully crafted xml comments weren't showing up in intellisense for my colleagues. Having always used the associated assemblies with project references, I hadn't realised that you had to export the .xml document as well to access this information. This led me to wondering how the .Ne...

What does the filterpriority tag in an XML comment do?

I have seen this in a lot of XML comments for classes in the .NET Framework BCL but have never been able to find documentation that explains what it does. As an example, looking at System.Object reveals the following comments: namespace System { /// <summary>Supports all classes in the .NET Framework class hierarchy /// and...

Code documentation: How much is too much?

How much code documentation in your .NET source is too much? Some background: I inherited a large codebase that I've talked about in some of the other questions I've posted here on SO. One of the "features" of this codebase is a God Class, a single static class with >3000 lines of code encompassing several dozen static methods. It's eve...

Link to a type not referenced by my project in XML comments?

I've come upon this situation a few times before. I wish to reference a type in my XML comments, but the type is contained in an assembly not referenced by my project. In A.Dll (references B.DLL): using B; ///<summary>Hai I'm SomeClass and I use <seealso cref="B.LoserClass"/> to do my work</summary> public class SomeClass {/*...*/} ...

XML Commenting tips for C# programming

Good morning, afternoon, evening or night (depending on your timezone). This is just a general question about XML commenting within C#. I have never been very big into commenting my programs, I've always been more of a verbose variable/property/method namer and letting the code speak for itself. I do write comments if I'm coding somethi...

Change default XML comment snippet in Visual Studio

When I hit /// in Visual Studio, is it possible to change the resulting snippet from this: /// <summary> /// /// </summary> to this?: /// <summary></summary> ...

How to link / group overloads in C# XML comments?

In XML documentaiton comments for C#, is there a way to mark two or more functions to be overloads of each other, so that they reference each other automatically? Ideally, they'd also be grouped in the sandcastle-generated documentation somehow. Purpose: Often, I want to link to this group of functions, e.g. in a list of utility functio...

How do I customize the auto commenting text in Visual Studio?

When I type the trigger the auto comment feature in Visual Studio (by typing "'''" or "///"), most of the XML commenting details show up that I like. However, I typically add the history tag to the documentation so I can track and changes that are made to the method over time. Is there any way I can customize the auto commenting feature...

XML Comments: To Use or Not To Use?

My co-workers rarely (if ever) use XML Comments when working on our software (I can't say I'm any better). I've recently seen the benefits of using them, but are they really worth it if the code they're documenting is written clearly (expressive/descriptive variable/function names, some in-line commenting)? Thanks! ...

How can you define and maintain XML code comments outside of the main solution?

I am building a public API and recognize the value of complete API documentation on public methods. I know it's easy to keep them in directly in code files as XML annotations on classes, methods, properties, etc. But I hate cluttering clean source code with public comments. What's the best way to create, and maintain XML code documenta...

How to have comments in IntelliSense for function in Visual Studio?

In Visual Studio and C#, when using a built in function such as ToString(), IntelliSense shows a yellow box explaining what it does. How can I have that for functions and properties I write? ...

Visual Studio 2008 XML Documentation

Hello, I can't seem to find the "Build" option under "Configuration Properties" folder in the Property Pages of my project. I've been looking everywhere trying to figure out how to do it. I followed the direations here: http://msdn.microsoft.com/en-us/magazine/cc302121.aspx More specifically here: http://msdn.microsoft.com/en-us/libr...

Using C#'s xml comment cref attribute with params syntax.

In C#, I am trying to use <see cref="blah"/> to reference a method signature that contains the params keyword. I know this converts the parameter list to an array, but I can't even figure out how to refer to an array in a CREF attribute. I am finding nothing in my searches and no one I know has any idea, either. The compiler is chokin...

Reference Prefixes in .NET XML Documentation

I've been attempting to fully document all types, methods, properties, etc. of a class library using XML comments but have run into a curious effect involving the cref attribute (used by see tags for example). Going by the advice of this MSDN page as well as following various other examples on MSDN and other websites, it seems that whene...