Reuse Code Documentation File

Topics: Questions
Sep 30, 2010 at 8:32 AM

Hi,

Is there a possibilty to reuse the documentation XML file which is produced by the build as an addtional documentation file? This would be a nice feature as in my WCF datacontracts all my members are already documented and unfortunately the WCF tools do not emit this information as annotation/documentation.

 

Many thanks for the very useful utility

Juerg

Coordinator
Oct 24, 2010 at 7:33 PM

Hi Juerg,

sorry for the late reply.

Unfortanately, there is no direct way to achieve what you want. However, I can fully understand why you want this behavior. Documentation works best if there is only a single source for the information. I think in your case keeping it in the C#/VB source files alongside with the WCF data types makes indeed the most sense.

The way I would attack this problem is as follows:

  1. Generate the XML documentation file out of the compiler (C#/VB). I guess you already do this today.
  2. Write yourself a tool that takes this file(s) as input and produces one or more external documentation files that can be used by XSDDoc.
    1. First, you need to understand how the XML documentation file is structured. The format is documented on MSDN.
    2. Second, you need to understand how external documentation works in XSDDoc. The is dicussed in the help file (which an be found in %ProgramData%\EWSoftware\Sandcastle Help File Builder\Components and Plug-Ins\XML Schema Documenter) under section Documenting - External Documentation.
    3. Third, you have to find out how C# entities are related to the XSD entities and create a mapping function. For example, I could imagine that a certain WCF contract type, such as T:MyCompany.MyService.ITheService relates to something like http://schema.mycompany.com#E/ITheService.
  3. All you then have to do is add those external documentation files to the SHFB project via the DocFilePaths property that can be configured in the plug-in configuration dialog of XSDDoc. I would keep them in a separate folder and use a wildcard to add them (such as WCFDocumentation\*.xml)
  4. Configure your build in a way that your tool runs after compilation and generates the external documentation file out of the documentation xml file produced by the compiler.

Hope this helps.

-Immo

Marked as answer by terrajobst on 2/15/2014 at 6:16 PM