Make svcutil pick up documentation from C# files?

Question

Folks,

I'm creating a new WCF Service and started with my Service interface. Looks something like:

   public interface ISomethingService
    {
        /// <summary>
        /// some description
        /// </summary>
        /// <version>2.13.0</version>
        /// <copyright>2009 by myself</copyright>
        /// <author>Marc Scheuner</author>
        /// <param name="request">The request object</param>
        [OperationContract]
        SomethingResponse GetList(SomethingRequest request);
    }

Now, I also created some data contracts in another file describing the SomethingRequest and SomethingResponse messages.

I compiled my project and fired up svcutil.exe to extract the metadata (WSDL and XSD) from the DLL - but I can't seem to figure out if there's a way to get all my comments and explanations into the WSDL/XSD into / nodes.

Am I blind for yet another obscure svcutil.exe parameter, or is there really no way to generate this documentation in the metadata automatically??

EDIT: ok, based on Marc Gravell's answer, the comments and documentation strings aren't in either the compiled DLL, nor available over the MEX metadata exchange protocol (pity!).

SO THEN: How do you document your WCF services, if you need to give a third-party the information they need to access your service?? Is there a "NService" or "Sandcastle for WCF" tool around that would scan my WCF service library and construct the WSDL and XSD from source code, including the annotations??

Can't seem to find a whole lot of tools and ways to do this - to my big surprise, honestly....

Marc

Answer 1

svcutil.exe consumes the "mex" API, and only has access to a subset of the metadata. Comments aren't included (nor, IIRC, is [DescriptionAttribute] to any great extent).

You might have to rely on external documentation (i.e. a help page / dead tree). One other option (although it breaks a number of pure SOA rules) is to ship the entities / interfaces in a dll + xml; svcutil (and the IDE) can re-use matching types from existing assemblies.

Answer 2

Maybe this helps: http://msdn.microsoft.com/en-us/library/aa717040.aspx

It works with svcutil as well.