I'm starting the process of creating API documentation for a web service API that my company is writing in C#, and am looking for advice on how to generate that documentation as automatically as possible. I've looked into various options, and none of them seem quite right for web service clients.
First I looked at using the Description property of the WebMethod attribute, but that doesn't really give you much room or flexibility for generating detailed API documentation. Plus, it's not internationalizable. Next, I looked at running NDOC on the web service assembly, which would be great (killer tool) except that it generates documentation for the server- side code, which doesn't necessarily match the client-side proxy code (for example, server-side collections become client-side arrays). Plus, it includes base-class code which is .Net specific (like ToString()), and I'd like to keep it moderately high level. If you look at the documentation for MapPoint.Net, for example, you'll see that it includes lots of .Net specific syntax, but the API descriptions are general enough that they could be translated easily to Java, et al. No ToString and GetHashCode methods there. Next, I looked at using NDOC along with a WSDL.EXE-generated proxy and the <include> documentation comment, keeping the actual documentation in a separate file. This gets the API right, but I don't really have a good way of automatically including the documentation elements for ALL the classes in one shot. As far as I can see the <include> tag is per-class, which means that I would have to paste in one <include> tag per class in the generated proxy. Since the WSDL can change (especially now during development) and require regenerating the proxy, this would result in a heck of a lot of manual file editing. Anyone have any other suggestions about how to go about doing this? I'd really rather not have to hack up the NDOC XSLTs or generate my own. Thanks, Kevin You can read messages from the DOTNET archive, unsubscribe from DOTNET, or subscribe to other DevelopMentor lists at http://discuss.develop.com.
