XML comments questions

[Clive Dixon]

Q1: The intellisense summary info for a class only seems to update after a
change to that class's XML comments if I remove the reference to the project
from the current project and add it back again. Why so, and how do I stop
this?

Q2: The <seealso> tag seems to be required (by Vis. Stu. 2003 at least) to
be inside the <summary> tag. However in the intellisense the seealso data
gets tagged onto the end of the summary info as a (as far as the user is
concerned) random floating typename of method. How do I prevent this?

Clive

 

[Nicholas Paldino [.NET/C# MVP]]

Clive,

Q1: I've never noticed this. It is possible that it is being cached. If
you are referencing the project, I would think that it would update
automatically. However, if you are not referencing the project, but rather,
referencing the DLL, you will have to do a recompile of the XML file.

Q2: Are you sure that you are including the ending slash, something like:

<summary>See the documentation for <seealso cref="MyClass"/>.</summary>

Hope this helps.

 

[Kevin Spencer]

Q1: The intellisense summary info for a class only seems to update after a

change to that class's XML comments if I remove the reference to the
project from the current project and add it back again. Why so, and how do
I stop this?

You need to configure your project to create the XML commenting when it
builds. This is done in the Project Properties dialog box.

Q2: The <seealso> tag seems to be required (by Vis. Stu. 2003 at least) to
be inside the <summary> tag. However in the intellisense the seealso data
gets tagged onto the end of the summary info as a (as far as the user is
concerned) random floating typename of method. How do I prevent this?

Good information here:

http://msdn2.microsoft.com/en-us/library/b2s063f7.aspx

--
HTH,

Kevin Spencer
Microsoft MVP
..Net Developer
A watched clock never boils.

 

[Jon Skeet [C# MVP]]

You need to configure your project to create the XML commenting when it
builds. This is done in the Project Properties dialog box.

I didn't think that affected things so long as the projects were all
within the same solution. Unfortunately, generating the XML
documentation for all builds often (for me, anyway) ends up requiring
restarts of VS.NET between builds, as it will lock the file which it
then needs to overwrite. I'm hoping VS 2005 is better on this score

 

[Kevin Spencer]

Hi Jon,

I should mention that I WAS talking about VS.Net 2005. My apologies if there
was any confusion. I keep forgetting that it is only now being released.
I've been working with it for about a year now.

VS.Net 2005 has no such issues with regards to building the comments on
compile. I am also much happier with the results. It does not generate HTML,
but XML Code Comment Reports. This is a much more flexible and extensible
format. In fact, I am currently working on an XSL transform to create our
own in-house software documentation library. Using XSL, I can organize the
documentation in any way I like, create cross-topic links, create a variety
of document types, and so on. The sort of things you can do with XSL. Kudos
to Microsoft on the new Comment model!

--
HTH,

Kevin Spencer
Microsoft MVP
..Net Developer
A watched clock never boils.

 

[Jon Skeet [C# MVP]]

I should mention that I WAS talking about VS.Net 2005. My apologies if there
was any confusion. I keep forgetting that it is only now being released.
I've been working with it for about a year now.

VS.Net 2005 has no such issues with regards to building the comments on
compile. I am also much happier with the results. It does not generate HTML,
but XML Code Comment Reports.

VS.NET 2003 does that already - although that's where the problems with
locking come in.

This is a much more flexible and extensible
format. In fact, I am currently working on an XSL transform to create our
own in-house software documentation library. Using XSL, I can organize the
documentation in any way I like, create cross-topic links, create a variety
of document types, and so on. The sort of things you can do with XSL. Kudos
to Microsoft on the new Comment model!

It's not new at all - it's been available for ages. You might want to
look at NDoc, which already builds docs in various different ways.

 

[Kevin Spencer]

Yeah, I've seen NDoc, but I won't learn anything by using it, so I'm rolling
my own. ;-)

--
HTH,

Kevin Spencer
Microsoft MVP
..Net Developer
A watched clock never boils.