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.

Solution 1

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.

Solution 2

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.

Solution 3

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.

Comments

[Farinha]

Will it also show up in the IDE? Like in Visual Studio's Intellisense?

[Joyce]

Just in case someone happens to find this, the latest is here. You can download using nuget as well.

[TylerY86]

WCFExtras' implementation is the superior option.

[TylerY86]

[elaboration] It ties the XML docs to the descriptor directly. Using XML docs is appropriate, but while Sandcastle or SHFB is absolutely appropriate for standalone documentation, it's just as 3rd party as WCFExtras, but less scenario specific.

[TylerY86]

While not immediately evident, the comment above references WCFExtras+, a different project, but a continuation of the work on WCFExtras. Good stuff.