xml documentation  
Author Message
mariascandella





PostPosted: XML and the .NET Framework, xml documentation Top

Hi!

I've a problem cos my boss wants to do a strange thing (i think so). i'm gonna try to explain it:

He wants to know how the .net generates the xml documentation when you programmer with c#. I mean which classes of .net are called to generate this xml. Basically, how (I supose) the compiler read (I supose) the .cs file and take just the documentation tags (<summary>,<param>...).

Once you've got just the tags you need, it's easy to generate the xml, but i don't know how to do the before step. I have an idea but i think it's not the optimal one. My idea is: open the .cs file and go through it looking for "///" or "/**" and take all the character until find other "///" or "*/". And repeat the same operation with all the files. I think is not a good idea.

Thanks, Maria

Ps: sorry for the bad english




.NET Development34  
 
 
Oleg Tkachenko





PostPosted: XML and the .NET Framework, xml documentation Top

Why can't you use C# compiler to generate documentation It comes with .NET Framework, you don't even need .NET Framework SDK to use it.

 
 
mariascandella





PostPosted: XML and the .NET Framework, xml documentation Top

 

Hi and thanks for your answer,

the things is that we want to do data base with all the documentation generated for our programmers in .net. So, when someone do a new application and need a specific method he could look for it in the data base and locate (if exists) the project or solution where this method is implemented. For this reason, we want to do like the c# compiler or ndoc do but with some differences.

I know how to generate the xml (like the compiler) and how to export these datas to a data base (in this particular case), but i don't know exactly how to extract the comments for the code and relate this comments with the object to which the code makes reference.

I hope it's clear. I know is a strange doubt, but if someone know how to do it, please tell me.



 
 
Sergey Dubinets





PostPosted: XML and the .NET Framework, xml documentation Top

It shouldn't be hard to extract comments from CS file. You can run RegEx for this for example. It will be much harder to figure out what method/or property this comment belongs to.

If you want to do this yourself you'd need to write your own C# compiler and support it for ever with new features added each release.

I'd suggest you to take some shortcut by letting csc generate PDB information for this file and then process PDB information to relate methods to positions in source file.

Reading PDB yourself is tricky but thank to Mike Stall we have suitable way of doing this: http://blogs.msdn.com/jmstall/archive/2005/08/25/pdb2xml.aspx



 
 
JussiA





PostPosted: XML and the .NET Framework, xml documentation Top

Hi,

Visual Studio generates xml-file, which contains the <summary>, <remarks> etc. information. This file is made during the compilation only if the VS project's properties has the "XML documentation file" value set.

So, open your VS solution, open your project and set the "XML documention file" property. Compile the project and look inside the xml-file.

For more information:

http://www.codeproject.com/csharp/csharpcommentinganddocs.asp

Hope this helps

/JussiA


 
 
Bill Rose





PostPosted: XML and the .NET Framework, xml documentation Top

I have run into an odd issue with this in VB.Net 2005. Most of my projects are upgrades from Studio 2003, and most generate xml documentation exactly as they should. But I have one that is newly created with 2005 which simply will not generate this file. The "Generate XML Documentation File" property is checked. I've compared every other project property I can see with those that are working in other projects. And I've tried cleaning the project both manually and from the Build menu. Any ideas