How to create Web Service documentation?

Topics: General Questions
Aug 13, 2007 at 2:46 PM
How would I go about creating documentation just for the public methods and classes of a custom web service?

Thanks.
Coordinator
Aug 13, 2007 at 5:13 PM
Hi,

Sandcastle cannot create documentation based on a web service's WSDL, if that's what you're asking. But if you have the assembly and an xml documentation file you can use Sandcastle in the same way as for any other type of code-base.

DocProject supports documenting Web Application projects by simply adding them as a project reference. If your web service is implemented in a Web Site project though, there are a few more steps you'll have to take but DocProject will support it as well.

For more information, see How To Build Help For a Web Site Project.

By default, DocProject only builds documentation for public APIs (but you can use the Documentation Scope option to document everything instead).

For general help working with DocProject see the How To... wiki.

- Dave
Aug 13, 2007 at 6:34 PM
Thanks Dave.

I have multiple assemblies and XML documentation files, however, there are internal classes, and methods that aren't exposed through the Web Service API, and so I wouldn't want them documented (or even included).

Is this something that could only be solved by having Sandcastle support documenting just what's exposed via the WSDL? or is there some other approach (or tool) that would do the job?

Thanks.

-Chris
Coordinator
Aug 13, 2007 at 8:02 PM
Edited Aug 13, 2007 at 8:02 PM
Hi Chris,

One approach would be to mark all of the non-public APIs as internal so that they will not be documented:

internal class SomeType { ... }
An alternative would be to use the API Topic Management Dialog to exclude those types and members that you do not wish to document.

- Dave