Web Api: enable XML documentation for your subproject (external assembly)

I would admit that this post it’s simply a copy/paste of a stackoverflow response, that was really well done and IMHO should also be in the documentation! of course I up-voted that post 🙂

There is no built-in way to achieve this. However, it requires only a few steps:

  1. Enable XML documentation for your subproject (from project properties / build) like you have for your Web API project. Except this time, route it directly to XmlDocument.xml so that it gets generated in your project’s root folder.
  2. Modify your Web API project’s postbuild event to copy this XML file into your App_Data folder:
    copy $(SolutionDir)SubProject\XmlDocument.xml $(ProjectDir)\App_Data\Subproject.xml

    Where Subproject.xml should be renamed to whatever your project’s name is plus .xml.

  3. Next open .Areas.HelpPage.HelpPageConfig and locate the following line:
    config.SetDocumentationProvider(new XmlDocumentationProvider(
        HttpContext.Current.Server.MapPath("~/App_Data/XmlDocument.xml")));

    This is the line you initially uncommented in order to enable XML help documentation in the first place. Replace that line with:

    config.SetDocumentationProvider(new XmlDocumentationProvider(
        HttpContext.Current.Server.MapPath("~/App_Data")));

    This step ensures that XmlDocumentationProvider is passed the directory that contains your XML files, rather than the specific XML file for your project.

  4. Finally, modify ./Areas/HelpPage/XmlDocumentationProvider in the following ways:
    1. Replace the _documentNavigator field with:
      private List<XPathNavigator> _documentNavigators = new List<XPathNavigator>();
    2. Replace the constructor with:
      public XmlDocumentationProvider(string appDataPath)
      {
          if (appDataPath == null)
          {
              throw new ArgumentNullException("appDataPath");
          }
      
          var files = new[] { "XmlDocument.xml", "Subproject.xml" };
          foreach (var file in files)
          {
              XPathDocument xpath = new XPathDocument(Path.Combine(appDataPath, file));
              _documentNavigators.Add(xpath.CreateNavigator());
          }
      }
    3. Add the following method below the constructor:
      private XPathNavigator SelectSingleNode(string selectExpression)
      {
          foreach (var navigator in _documentNavigators)
          {
              var propertyNode = navigator.SelectSingleNode(selectExpression);
              if (propertyNode != null)
                  return propertyNode;
          }
          return null;
      }
    4. And last, fix all compiler errors (there should be three) resulting in references to _documentNavigator.SelectSingleNode and remove the _documentNavigator. portion so that it now calls the new SelectSingleNode method we defined above.

    This Last step is what modifies the document provider to support looking within multiple XML documents for the help text rather than just the primary project’s.

    Now when you examine your Help documentation, it will include XML documentation from types in your related project.

Advertisements