Need guidance to document a wcf service

Topics: User Forum
Aug 1, 2013 at 3:25 PM
Hello,

I wonder is there any guidance how to document a web (wcf) service for the service consumers?
In fact, there is no problem to document the web service interface as a part of web service project, however, it exposes the internal naming for namespaces, classes etc.
What I need is to document the wsdl which contains the api exposed to clients but ideally re-use the comments applied to the interface and underlying classes, enums etc.

Any help will be greatly appreciated.
Thanks In advance.
Coordinator
Aug 1, 2013 at 8:17 PM
Sandcastle and SHFB are designed to document assemblies. You could use conceptual content to document the service though you'd have to do it all and wouldn't be able to pull in the comments from the code. It's possible you could create a custom configuration and presentation style to pull in just the stuff you need but that's probably a lot of work.

Eric
Aug 2, 2013 at 3:00 PM
Edited Aug 3, 2013 at 2:04 AM
I've found Sandcastle to be quite useful for documenting WCF services, especially for an audience of developers who are likely to use the service in .NET apps. I usually start by creating a sample application in Visual Studio with a reference to the service I'm documenting. I then create a Sandcastle documentation project to document the service, and I use the service reference DLL as the documentation source. This allows me to present the namespaces and types as clients see them. Of course, everything will ultimately appear under the namespace of the sample application, but your namespace summary can explain that it's just an example of a namespace for a service proxy generated by adding a service reference in Visual Studio.

That said, most of my semantic documentation about the service is contained in conceptual topics, and I just link to the reflection documentation when referring to specific types, methods, etc. I haven't so far made use of code comments, but I do know of a NuGet package called WCFExtras+ that can add code comments for a service to the WSDL. The developers of the service would need to install the package in their project and decorate the service contract with an [XmlComments] attribute, and clients also have to install the package if they want to see the comments in the proxy code. If you take the approach described above, your sample client application could install the package to import the comments into its proxy code, and your Sandcastle project would pick up the comments when you add the proxy DLL to your Sandcastle project as a documentation source.
Aug 2, 2013 at 5:16 PM
Edited Aug 2, 2013 at 7:21 PM
Thanks Charlie, sounds encouraging! Based on your recommendations I did:
  1. Create a client project in Visual Studio to be documented.
  2. Added a service reference to the wcf service. It created a proxy class with the expected service API method/classes/enum/member names. However, no comments were propagated to the proxy.
  3. Create a new Sandcastle documentation project for the client project.
  4. Not sure how "use the service reference DLL as the documentation source"?
I'm quite new to Sandcastle and SHFB so could you elaborate more on steps to be done.

Much appreciated and thanks in advance!
Aug 3, 2013 at 2:04 AM
Happy to help! To explain what step 4 involves: as Eric noted, Sandcastle is designed to document assemblies. Adding a documentation source tells Sandcastle where to find the DLL(s) you want to document. In this case, you're documenting the DLL for the service proxy that Visual Studio generated when you added the service reference. This can be found in the Debug\TempPE folder of your client project (e.g., ..\Debug\TempPE\Service References.MyService.dll).

In SHFB or in the Sandcastle Visual Studio plugin, right-click Documentation Sources, select Add Documentation Source, and browse to the service proxy DLL. This makes Sandcastle aware of the types and methods exposed by the service when it builds the documentation project. Within your documentation project's conceptual topics, you can now create <codeEntityReference> links to the methods, types, etc., that are contained within the service proxy.

As you noted, the code comments are not propagated to the proxy. As far as I am aware, the only way to do this is by using a tool like WCFExtras+, as described above. WCFExtras+ needs to be installed in the service project to add the comments to the WSDL and installed in the client project to read them from the WSDL and add them to the service proxy code. Once you have done this and then added a reference to the proxy DLL as a documentation source, Sandcastle should pick up the code comments when it generates the reflection documentation.

Let me know if you have trouble getting any of this to work.
Aug 6, 2013 at 2:04 PM
Thanks Charlie, that works.
I'll look into WCFExtras+ (weird but tool last updated in 2009 and nothing else available). Fyi, found another way to build a custom wcf extension to generate documentation.
Aug 7, 2013 at 1:26 PM
EWoodruff wrote:
Sandcastle and SHFB are designed to document assemblies. You could use conceptual content to document the service though you'd have to do it all and wouldn't be able to pull in the comments from the code. It's possible you could create a custom configuration and presentation style to pull in just the stuff you need but that's probably a lot of work.

Eric
Hi Eric,

I'd like to confirm with you if the scenario below is possible:
  1. Document a wcf contract assembly as is.
  2. Then change an intermediate files (if any available) generated by SHFB to change names for namespaces and some class names etc.
  3. Build chm, from the updated files.
Coordinator
Aug 7, 2013 at 8:06 PM
Using a plug-in, it would be possible. It could run after the generation of reflection information. At that point, everything you need should be in the working folder that may need modifying (XML comments files, the reflection information file, and any MAML topics). Your plug-in's configuration would specify which namespaces and class names to change and how to change them. See the Creating Build Process Plug-Ins topic for more information.

Eric