C# XML documentation comments FAQ

paraesthesia

paraesthesia — Tue, 12 Sep 2006 19:48:58 GMT

PingBack from http://www.paraesthesia.com/blog/weblog.php?id=P1076

re: C# XML documentation comments FAQ

Patrick — Tue, 12 Sep 2006 22:09:54 GMT

Creating a .CHM file or other type of documentation file from the XML comments is an important feature with a lot of demand around it (just look at the number of downloads nDoc gets). Having more verbose comments ala GhostDoc is also something that is highly useful.

Being able to keep the documentation and the code in the same document (the .cs file) makes it far more likely that the documentation will actually stay up to date.

The XML comments feature should be expanded to include images, samples, and other expository text.

ResponseI agree with your suggestions and we're tracking them on a potential features list for a future version of VS.

re: C# XML documentation comments FAQ

Nikita A Zeemin — Fri, 15 Sep 2006 07:13:42 GMT

Greate post, thanks a lot! I just translated it to Russian and want to publish it on famous Russian programmer's site/forum http://rsdn.ru/ ("Russian Software Developers Network"). Can you grant me your permission to this? Of course, your copyright will be saved with the translated version of the article.

ResponseSure! I've got no problem with any of these posts being translated into other languages. Thanks for taking the time to do so :)

Community Convergence III

Charlie Calvert's Community Blog — Fri, 15 Sep 2006 08:24:41 GMT

This week you can watch the first in a series of videos featuring members of the Microsoft C# team. A video of Raj Pai, the Group Program Manager for the C# team, leads off the series.

re: C# XML documentation comments FAQ

Jan Kucera — Fri, 15 Sep 2006 11:58:39 GMT

Unfortunately there is no way of reflection on the comments as far as I know...

Russian-translated version

nzeemin — Tue, 19 Sep 2006 07:56:09 GMT

So, here is Russian-translated version of the post: http://rsdn.ru/article/devtools/CSxmlcmnt.xml

ResponseAwesome! Thanks!

Embedding Doc Comments as Metadata

Chris — Thu, 21 Sep 2006 15:22:24 GMT

Has there been any consideration of providing a step in the compilation process that would inject documentation comments into an assembly, thus making it possible to discover documentation comments via reflection? This could easily be accomplished via attributes and it would be quite useful to tool developers. It would also make an assembly "self-documenting" without having to worry about toting around an additional *.xml file

ResponseGood question. Honestly the choice to split the documentation and the metadata/il was intentional. There are a few reasons. The first is that the documentation is really useful only when developing an application, which tends to be a comparitvely small amount of the time as compared to its usage in running the application. That wouldn't make much of a difference if it were free to make use of attributes; however, there is a cost both in the size of the assembly and the load time. So, we decided to split it out such that a fairly trimed down version could be deployed to end users with the documentation being deployed separately to developers.

I generally think this was the right choice; however, I definitely agree that we should have and promote and easy way to access doc comment information. It sounds like an interesting topic for a future blog.

C# Generic Documentation Comment.

Clayton Firth's Blog — Thu, 05 Oct 2006 02:50:22 GMT

I have been struggling with this issue for a few weeks now. How to I put crefs into my C# doc comments...

C# Links

Charlie Calvert's Community Blog — Tue, 10 Oct 2006 03:54:25 GMT

Learn Videos and Presentations The LINQ Framework: What's New in the May CTP Anders: Chatting about LINQ

re: C# XML documentation comments FAQ

Joe — Tue, 31 Oct 2006 12:26:43 GMT

One of your examples has a comment stating 'DoSomething takes a <see cref="List{T}"/>'.

In fact DoSomething takes a List<int>, not just any List<T>. Is there a way to specify this constraint in the XML comments?

re: C# XML documentation comments FAQ

Chris Moore — Fri, 03 Nov 2006 01:37:56 GMT

Yes! Yes! Yes!

I totally agree with the comment above by Chris (not me, the other Chris) that there should be an option to embed documentation comments into an assembly. I spent days writing a unified reflection model (an Assembly DOM, if you will) that provided the documentation comments for a given type, method, etc. I work a lot with reflection and many, many times I have needed this information.

How lovely it would be to write:

DocComments comments = typeof(MyType).DocComments.

!!!!

re: C# XML documentation comments FAQ

Mr. R — Mon, 18 Dec 2006 11:45:10 GMT

I'm sorry, but... the last post, and the other referencing the whole "reflection of comments" is nothing short of laughable.

I don't mean to be rude, but you guys do realize that when something is COMPILED that the comments are considered whitespace, right? And that when they're stripped, they're stored in an .xml comments file (if specified).

The latter request is just about as a horrible idea as any. I don't know about you, but no developer worth their weight in salt (or gold) would ever want the comments compiled in to their assembly, not any part. If you -really- want this, look at doing something msbuild and resources... don't, don't, don't ask anyone on any team even remotely close to the .NET Framework to add such a feature.

This is a request that I can only assume is being made by people that really don't have a clue how something compiles, or aren't just thinking this through.

How 'bout you guys look up the comments from the xml markup during the reflection process? Is it really that hard?

The response to the first post obviously shows that they were thinking this through. At least someone over there is. ;-)

Reverse Enginnering of the "doc comments"???

akashelkar — Wed, 10 Jan 2007 15:27:36 GMT

Is there a way I can generate the code comments back from an XML document? For e.g. if I have a code module in which I have added "doc comments" at various places and I generate an XML file from these comments. Can I have an XML file made in the same format and then reverse-engineer it somehow to get the comments underlying it?

If this were possible, I could create my functional/technical specs in the XML format and then reverse-enginner it to have the specs entered into an existing or a blank code file as comments. Easy reference when writing code!

re: C# XML documentation comments FAQ

Roman Korchagin — Sat, 27 Jan 2007 04:48:16 GMT

It would be great if there was any guideline on writing the <exception> documentation tags.

The .NET Framework Guidelines book gives plenty of guidelines on using exceptions, but nothing about documenting exceptions thrown by a method.

I fully agree and support that the exception specification is not part of the C# language, but documenting what exceptions are thrown by a method in a public API is an entirely different thing and I think it must be done. The .NET Framework itself documents thrown exceptions thoroughly.

I'm a lead developer of a popular commercial component and we were not documenting thrown exceptions, but the users ask for this and we must formulate a strategy.

The question is basically is:

I have a public API method A which calls heaps of internal methods and heaps of .NET framework methods and classes.

What <exception> documentation should I include in the documentation of the method A?

a. Should I document only exceptions thrown explicitly by method A?

b. Should I document ALL possible exceptions that can be thrown by method A and ANY method that it calls?

If I do "a", then it is easy to mislead the users by "underdocumentation". For example I have a public method Load that does something simple and calls the more meaty internal method LoadCore. It makes no sense to document exceptions thrown only by the Load method since there are none. Then I must do "b".

However, it is very hard to do "b" properly because it requires a lot of maintenance! Basically it means the documentation for exceptions for a public method will depend on the actual implementation that could be deep down. For example, I changed the implementation of the Load method to use different .NET methods and classes and they throw different exceptions now. I should then manually find and update all exception documentation that could be affected!!!

So I think I will stick with NO <exception> documentation for the time being.

Thanks.

re: C# XML documentation comments FAQ

Roman Korchagin — Sat, 27 Jan 2007 05:10:55 GMT

In addition to my previous comment about <exception> documentation I would like to say that creating some sort of an automatic tool that will follow the call tree from the public method A into all internals to collect documentation for all thrown exceptions is not going to solve the problem.

For example, deep in my code I access an element of some internal array. You know this can thrown IndexOutOfRangeException, but hopefully, I wrote stable code that will not do such thing. Therefore, I expect that IndexOutOfRangeException will never be thrown and I certainly don't want to document it in the public API.

So it looks like there is no escape from the hard work in this case? How you did this for MSDN at Microsoft?

re: C# XML documentation comments FAQ

Fornaris — Sat, 03 Feb 2007 11:55:40 GMT

Hi!

How I can add some contents to the documentation without a class definition? For example:

Introduccion

What's new

Bugs

Abstract

Bla, bla..

re: C# XML documentation comments FAQ

ocnsss — Tue, 27 Mar 2007 10:38:28 GMT

On personal opinion, I find this very helpful.

Guys, I have also posted some more relevant info further on this, not sure if you find it useful: http://www.bidmaxhost.com/forum/

re: C# XML documentation comments FAQ

Albert — Tue, 15 May 2007 12:41:25 GMT

What is your opinion about documenting overriden methods in c# code ?

What is the best practice for this and what are the consequencies in the final documentation ?

re: C# XML documentation comments FAQ

Matt Galligan — Wed, 27 Jun 2007 15:53:27 GMT

CHM Documents are nice, but with a little photoshop skill, and a XSL sheet you can create essentially the same thing. Using CSS positioning or frames to create a TOC and automatic linking throughout the document.

You can even link back to parent or related classes, link through the <seealso> tag,etc.

It took me about a day of work to make a nice XSL file that will last me for the entirety I use .NET.

...And you dont have to worry about NDoc.

re: C# XML documentation comments FAQ

Allann — Tue, 17 Jul 2007 08:41:41 GMT

Hi,

This might be a little of topic, but how do you specify a code segment enclosed in the <code> tags as being a specific language so that the laguage filter will work?

Thanks in advance

Allan

motorcycle blog » C# Generic Documentation Comment.

motorcycle blog » C# Generic Documentation Comment. — Mon, 30 Jul 2007 11:01:23 GMT

PingBack from http://www.webkes.info/2007/07/30/c-generic-documentation-comment/

re: C# XML documentation comments FAQ

Benoist — Tue, 31 Jul 2007 13:09:28 GMT

What about alias ?

Can we use them is cref ?

Using MyCtrl = MyNamespace.Controls;

class Program

{

/// <summary>

/// DoSomething takes a <see cref="MyCtrl.MyControl>"/>

/// </summary>

void DoSomething(MyCtrl.MyControl control) { }

}

re: C# XML documentation comments FAQ

Sean Aitken — Tue, 31 Jul 2007 17:33:56 GMT

I agree with Anson. The separation makes a lot of sense. I still come from the belief that wasting space is a bad idea, no matter how trivial it seems. Maybe the reflection API's could be added, but rather than embedding the docs, they would look for the associated XML doccomments files. Many tools I find now are coming with the compiled xml.

re: C# XML documentation comments FAQ

asp.net — Thu, 04 Oct 2007 16:41:29 GMT

how to create xml comment file of website to provide as input to sandcastle

public members only?

Ignaz — Tue, 30 Oct 2007 19:12:00 GMT

Is there a way to extract the XML doc comments for public members only? I use the same commenting style for internal and private members, but don't want to deploy those comments.

.NET XML Comments

Warren Tang — Mon, 14 Jan 2008 04:26:56 GMT

Reference C#XMLdocumentationcommentsFAQ

http://blogs.msdn.com/ansonh/archive/2006/09/11/750...

.NET XML Comments

Warren Tang — Mon, 14 Jan 2008 04:27:06 GMT

Reference C#XMLdocumentationcommentsFAQ

http://blogs.msdn.com/ansonh/archive/2006/09/11/750...

Website Scripts » Anson Horton’s Blog : C# XML documentation comments FAQ

Website Scripts » Anson Horton’s Blog : C# XML documentation comments FAQ — Mon, 21 Jan 2008 08:29:31 GMT

PingBack from http://websitescripts.247blogging.info/anson-hortons-blog-c-xml-documentation-comments-faq/

re: C# XML documentation comments FAQ

Andy — Thu, 31 Jan 2008 07:00:42 GMT

How to type character < less than in XML comment ?

re: C# XML documentation comments FAQ

Maggie — Sat, 02 Feb 2008 00:28:02 GMT

In Visual Studio 2005, whenever I try to put a less than sign (left angle bracket) after \n"/// " (space after third slash), the IDE hangs. I hold shift then hit < and I never get control back. Is this a known bug, I could not find any reference to it on the web.

re: C# XML documentation comments FAQ

John S — Wed, 19 Mar 2008 20:21:57 GMT

Hi there, thanks for the informative article. You talk about making cross references to generic types, eg:

/// <summary>

/// Populates the <see cref="Stack{int}"/>.

/// </summary>

So here we have defined a cref to a generic stack of ints. The type information has been put in braces instead of <> and VS recognises this correctly. However, what if the contained type is generic itself? I would have guessed that the following should work:

/// <summary>

/// Populates the <see cref="Stack{List{int}}"/>.

/// </summary>

The type referenced above is a generic stack that contains a generic list of ints. It is a perfectly valid construct yet the brace syntax demonstrated above does not work. It results in an unresolved reference to Stack<List<int>>, even though the referenced types are in the current compilation scope. It would appear that the brace syntax only works for generic types that are 'one level deep' as it were.

So please, how would you make a cross reference to a generic type that contains a generic type, such as in the above example?

Thank you for your time.

re: C# XML documentation comments FAQ

Jim Blackler — Sun, 23 Mar 2008 18:07:13 GMT

".. there should be an option to embed documentation comments into an assembly. How lovely it would be to write:

DocComments comments = typeof(MyType).DocComments."

I have written a small class library called DocsByReflection that doesn't embed the comments into assembly but does provide a simple way to get the information from the XML, in a similar way to how you have described.

I hope some find it useful, it is documented here:

http://jimblackler.net/blog/?p=49

Copyright Revewals » Anson Horton’s Blog : C# XML documentation comments FAQ

PingBack from http://copyrightrenewalsblog.info/anson-hortons-blog-c-xml-documentation-comments-faq/

re: C# XML documentation comments FAQ

Driver — Wed, 25 Jun 2008 16:34:44 GMT

Hi,

This week you can watch the first in a series of videos featuring members of the Microsoft C# team. A video of Raj Pai, the Group Program Manager for the C# team, leads off the series.

thanks.

re: C# XML documentation comments FAQ

sex — Mon, 14 Jul 2008 23:11:24 GMT

Learn Videos and Presentations The LINQ Framework: What's New in the May CTP Anders: Chatting about LINQ

re: C# XML documentation comments FAQ

Andrew — Fri, 12 Sep 2008 17:12:54 GMT

GhostDoc has generated the following for me:

The compiler warns me that this is not syntactically correct. Am I missing something?

re: C# XML documentation comments FAQ

Gerrit — Sun, 01 Feb 2009 04:01:18 GMT

Why do I have to read/write unreadable xml? XML should not be written or read by humans. Please, can I get something more readable like JavaDoc style?

Anson Horton s Blog C XML documentation comments FAQ | storage bench

Anson Horton s Blog C XML documentation comments FAQ | storage bench — Sun, 14 Jun 2009 13:26:08 GMT

PingBack from http://thestoragebench.info/story.php?id=887

re: C# XML documentation comments FAQ

Andrew Shapira — Tue, 03 Nov 2009 18:29:50 GMT

Suggestion: mention the syntax <typeparam name="T"> in the section, "How do use XML doc comments to refer to generic types?", or, add a new nearby section that describes typeparam. It's necessary to know the typeparam syntax in order to document generic types, and the syntax is not obvious a priori.