4

I am exposing my API through web service (.asmx). Currently, the only thing available is the default WSDL help page. While this is immensely helpful, it is not sufficient if my target audience requires a little more hand-holding. For instance, let us say I want to include some examples but still need automatic generation of method signatures etc.

Is there a good semi-automated (automatic method signatures but still be able to provide examples) to achieve this? I am looking for something like this which is also maintainable. Ideally something that helps me modify the default WSDL (I really like that page) would be great. All I need is for the documentation to be automatically available along with the service when it is deployed.

Any suggestions?

Legend
  • 113,822
  • 119
  • 272
  • 400

3 Answers3

1

Maybe easiest way is to use XML documentation comments.

XML Documentation Comments

Using these comment you can automatically generate HTML documentation. For example using Sandcastle or NDoc3:

Build Sandcastle Documentation When Building Visual Studio Project

And after all you can automatically save html documentation into shared location near your service, and it could be easily navigated there using browser. So, all could be near - wsdl + html documentation

Community
  • 1
  • 1
Regfor
  • 8,515
  • 1
  • 38
  • 51
0

This is fairly easy. If you decorate all your classes and methods with tripple /// comments then you could generate documentation from it. See here:

http://msdn.microsoft.com/en-us/library/dd233217.aspx

http://www.developerfusion.com/article/84436/documentation-made-easy-with-c-and-xml/

fenix2222
  • 4,602
  • 4
  • 33
  • 56
0

Agree with other posters, however I've used NDoc3 with a lot of success. It's quite a bit faster than Sandcastle (which is a very good tool as well). NDoc3 will create .chm, .doc, and .html output.

NDoc3 and Sandcastle both generate MSDN-style documentation.

NDoc3 - http://sourceforge.net/projects/ndoc3/

Rick
  • 1