Best way to document WCF interface?

Question

So I'm using WCF, and want to document my interface(s) and services to give to another company for an internal app. What's the best way to document those interfaces? I'd prefer having the documentation inline with the code, and then have something prettify to output HTML, but am not sure if there's a recommended way to do it.

Thanks.

Answer 1

Using the XML output from the compiler is nice...but it's been my experience that it's difficult to express the complete complexity of a service and it's expected invariants, dependencies, etc. in comments alone. You're better off maintaining a separate real document (Word, HTML, Wiki) to cover it all.

Answer 2

I use two XSL files - one to document the WSDL for the operations, one to document the XSD for the data being passed around.

Unfortunately, so far, I haven't found a single cohesive solution, so I work with two XSLT files which transform the WSDL and the XSD respectively into HTML documentation.

WSDL Viewer does the job for the WSDL and produces a first HTML document, and xs3p does the same for the data contain in the XSD file.

Works for me, at least for now :-)

Marc

Answer 3

Do use XML docs for that. There are a lot of smart meta-tags that will allow you to put code samples in them, references between operations, thrown exceptions etc.

Then you can use Sandcastle (+ some GUI you can find on Codeplex) to generate either chm, or html documentation.

Answer 4

I will put my interface contract into a common dll and hand that out. It gives them both the xml comments on the contract without giving the details of the service as well as allowing them to implement the service in an offline mode for testing until they're ready to use it. On top of that, they can bypass the wsdl and use ChannelFactory to create a channel.

Answer 5

We use WCFExtras (http://www.codeplex.com/WCFExtras) for that.

Among other features it allows live exporting of your code xml comments into the generated WSDL, for example check how these xml comments:

    /// <summary>
    /// Retrieve the tickets information for the specified order
    /// </summary>
    /// <param name="orderId">Order ID</param>
    /// <returns>Tickets data</returns>
    [OperationContract]
    TicketsDto GetTickets(int orderId);

get reflected in the WSDL of that interface:

    <wsdl:operation name="GetTickets">
    <wsdl:documentation>
    <summary> Retrieve the tickets information for the specified order </summary> <param name="orderId">Order ID</param> <returns>Tickets data</returns>
    </wsdl:documentation>
    <wsdl:input wsaw:Action="xxxx" message="tns:PartnerAPI_GetTickets_InputMessage"/>
    <wsdl:output wsaw:Action="xxxx" message="tns:PartnerAPI_GetTickets_OutputMessage"/>
    </wsdl:operation>

An excerpt from their docs:

Adding WSDL Documentation from Source Code XML Comments This extension allows you to add WSDL documentation (annotaiton) directly from XML comments in your source file. These comments will be published as part of the WSDL and are available for WSDL tools that know how to take advantage of them (e.g. Apache Axis wsdl2java and others). Release 2.0 also includes a client side WSDL importer that will turn those WSDL comments to XML comments in the generated proxy code.