Generating API documentation in visual studio 2005 environment

Generating API documentation in visual studio 2005 environment

• RynBev

  Mark Dawson wrote:

  If you are using .Net 2.0 then NDoc will not work for you since it does not support all the features, plus support and development I believe has been discontinued. Mark.

  I have refered to the version of nDoc which supports .Net 2.0. Yes may be it doesnot support all the features because its not the final release.

  Best Regards,

  Rizwan aka RizwanSharp

  
  
  

• Zapp

  I have problems using the tools. it seems that it is a tedious process for me to figure out how the sandcastle commands works with a given .xml file. Could someone help me simplify the steps if you have used it before thanks
  

• Alexan

  If you are using .Net 2.0 then NDoc will not work for you since it does not support all the features, plus support and development I believe has been discontinued.

  Mark.

  
  
  

• shmulik_segal

  I have followed the steps in sandcastle's blog but i got lost

  1) Given a C# project, when I build accordingly to generate a xml file, if there are several C# files, will only 1 XML file be generated

  2) In the instructions, they mentioned about a .dll file being created but I can't find it after I build the solution

  3)It mentioned to alter the sandcastle's config file, but I am having problems with that too. sigh

  4)sandcastle has no GUI, so I am not really good at reading all the wordy instructions. could anyone help to simplify the process i.e. let's say I already generated a .xml file called XMLDoc.xml

  Thanks a million.

  
  

• Tsuchida

  Hi,

  the XML in the code is just to provide a set format for the information to be captured. When you compile your code it generates an XML document file that can then be used by applications like Sandcastle of Document X to transform the XML into HTML documents that look like MSDN. So you really have the following stages:

  1. Add XML comments to the code

  2. Compile the code and generate XML Document files (still raw XML at this point)

  3. Insert Xml Doc file into a tool like Sandcastle

  4. Sandcastle converts XML info into appropriate output format, like HTML.

  Mark.

  
  
  

• markwickens

  Mark Dawson wrote:

  I believe it is the final release since there has not been any work on the project in nearly a year :-) For 1.1 I would recommend NDoc but probably not for 2.0. Mark.

  May be but I have used nDoc with .Net 2.0 at my office but if its discontinued (I dont know about this) then I think Microsoft Sandcas..... is better.

  Best Regards,

  Rizwan aka RizwanSharp

  
  
  

• Luxsy

  You can try NDoc like Rizwan mentioned that was very easy to use, it might be functional enough to suit your needs. In regards to your dll or exe you should have a bin/debug and bin/release folder under where your project source files are located on disk.

  Mark.

  
  
  

• Kamii47

  Hi,

  try this: http://www.codeproject.com/useritems/SandcastleBuilder.asp it is a gui frontend to sandcastle, I have not used it so I cannot vouch for how good it is.

  1. You will get one xml doc file per project

  2. This is the dll of your project, or exe if it is an executable.

  3. What problems

  4. See above.

  Mark.

  
  
  

• DocMARs

  thanks. it was useful. but i have a question. I am new to XML, therefore I wish to know if I could get it to display like how MSDN API or the Java API looks like without the tags. The display is not very friendly. =S
  
  

• Waltari

  Hi,

  if you want to create documentation then you can use Xml Documentation. This is when you use three slashes i.e. /// to write the comments in your code

  /// <summary>
  /// This method does nothing
  /// </summary>
  /// <param name="name">The name of the person</param>
  /// <returns>The total number of characters in the name</returns>
  public static int Foo(string name)
  {
  }

  For more information on the tags you can use, see: http://msdn.microsoft.com/library/default.asp url=/library/en-us/csref/html/vcoriXMLDocumentation.asp

  Once you have entered these comments you need some tool to generate documentation from the XML, Microsoft have a new tool called Sandcastle that can do this, see:

  http://www.codeproject.com/useritems/ccnetsandcastle.asp

  http://www.microsoft.com/downloads/details.aspx FamilyId=E82EA71D-DA89-42EE-A715-696E3A4873B2&displaylang=en

  Hope that helps

  Mark.

  
  
  

• Mikhail Ryzhinskiy

  You can add Xml Comments to your code, Compile it and then use nDoc tool(Free & Open Source) to generate chm, web, MSDN styled documents.

  Here is the download link:

  http://community.rainbowportal.net/blogs/jonathans_rainbow_blog/archive/2006/03/21/1685.aspx

  Best Regards,

  Rizwan aka RizwanSharp

  
  
  

• DiamonDogX

  oh thanks

  1) ok thanks for the clarification

  2)That's the problem. Can't seem to locate the dll nor the exe. I have the Visual C# Project file, sources files and all the others except the dll and the exe. =S Can't sandcastle just make do with the .xml file alone

  3)I went to this site to have a look at his batch file http://ixnay2infinity.blogspot.com/2006/07/batch-file-for-microsoft-sandcastle.html

  but I have problems because I do not know how to go about editing his batch file to suit my needs. I just want to have my XMLDoc.xml generated. but the steps are rather cumbersome and tedious.

  4)It seems the GUI is also quite complex =)

  
  

• Swaykid

  thanks. NDoc seems to be working well for me as for now. I will explore into sandcastle when I have the time. Thanks a lot for the technical help. else I will be surfing for days
  

• indersunny

  I believe it is the final release since there has not been any work on the project in nearly a year :-) For 1.1 I would recommend NDoc but probably not for 2.0.

  Mark.

  
  
  
• Generating API documentation in visual studio 2005 environment