<inheritdoc/> problem when implementing an interface located in a different assembly

Topics: Project Management Forum, User Forum
Nov 10, 2014 at 2:21 PM
Hi all,

I have a problem to apply <inheritdoc/> to members of a class (named HeatTransitionCoefficientCalculatorHxSingleRow) implementing members of an interface (named IHeatTransitionCoefficientCalculator) residing in a different assembly. Both projects (one containing the implementing class, the other containing the interface to implement) are added to the SHFB project.
When building the SHFB project problems finding appropriate comments are indicated:
SHFB: Warning GID0004: No comments found for member "M:ECS....Simulation.HeatTransitionCoefficientCalculatorHxSingleRow.CalculateKaFromHeatFlow (...)".

The XML file for the assembly containing the implementing class (ECS.....Simulation.xml) shows that the comments are subject to inheritance:
<member name="M:ECS.....Simulation.HeatTransitionCoefficientCalculatorHxSingleRow.CalculateKaFromHeatFlow(..)">
            <inheritdoc/>
        </member>   
The XML file for the assembly containing the interface to implement (ECS.....Interfaces.xml) contains the comments to be inherited:
-<member name="M:ECS.....Interfaces.SimulationMethods.IHeatTransitionCoefficientCalculator.CalculateKaFromHeatFlow(...)">
<summary> Calculates the heat transition coefficient 'k' from a given heat flow. </summary>
...
<returns>The heat transition coefficient 'k' [W/m²/K].</returns>
</member>
A closer look at the reflection.xml file reveals that the entry for method CalculateKaFromHeatFlow lacks the <implements> tag refering to the interface to implement (IHeatTransitionCoefficientCalculator):
<api id="M:ECS.....Simulation.HeatTransitionCoefficientCalculatorHxSingleRow.CalculateKaFromHeatFlow(...)">
      <topicdata group="api" />
      <apidata name="CalculateKaFromHeatFlow" group="member" subgroup="method" />
      <memberdata visibility="public" />
      <proceduredata virtual="true" final="true" />
      <parameters>
        ...
      </parameters>
      <returns>
        <type api="T:Units.HeatTransitionCoefficient" ref="false" />
      </returns>
      <containers>
        <library assembly="ECS.....Simulation" module="ECS.....Simulation" kind="DynamicallyLinkedLibrary">
          <assemblydata version="10.1" />
          <noAptca />
        </library>
        <namespace api="N:ECS.....Simulation" />
        <type api="T:ECS.....Simulation.HeatTransitionCoefficientCalculatorHxSingleRow" ref="true" />
      </containers>
      <file name="bebff12b-4563-8631-95f9-25f0833a9784" />
    </api>
When I explicitely refer in the implementing class to the interface (e.g. <inheritdoc cref="IHeatTransitionCoefficientCalculator.CalculateKaFromHeatFlow") everthing is working as expected. It seems that somehow MREFBUILDER skips the dependency to the interface IHeatTransitionCoefficientCalculator.

Suggestions are appreciated.

Regards,
Mario
Coordinator
Nov 10, 2014 at 5:45 PM
Inherited documentation won't be found if you haven't included the XML comments file for the reference assembly in the project. You can add it directly or use the Additional Reference Links plug-in to supply both it and reference link info to suppress the "missing reference link" warnings that occur in the BuildAssembler step.

Eric
Nov 11, 2014 at 7:36 AM
Hello Eric,

thank you very much for the quick reply.

I think both XML comments files are included since both projects (the one containing the interface and the other containing the implementing class) have been added to the SHFB project.

This is excerpt of last build's log:
<?xml version="1.0" encoding="utf-8"?>
<shfbBuild product="Sandcastle Help File Builder" version="2014.5.31.0" projectFile="C:\entwickl\...-ts\Development\Main\ECS.NET\ECS.NET.Documentation\ECS.NET.Documentation.shfbproj" started="10.11.2014 15:07:51">
<buildStep step="Initializing">
Finding tools...
The Sandcastle tools are located in &#39;C:\Program Files (x86)\EWSoftware\Sandcastle Help File Builder\&#39;
Locating components in the following folder(s):
   C:\entwickl\...-ts\Development\Main\ECS.NET\ECS.NET.Documentation
Using presentation style &#39;VS2013&#39; located in &#39;C:\Program Files (x86)\EWSoftware\Sandcastle Help File Builder\PresentationStyles\VS2013&#39;
Loading and initializing plug-ins...
Lightweight Website Style Version 2014.5.31.0
Copyright &#169; 2006-2014, Eric Woodruff, All Rights Reserved
Portions Copyright &#169; 2014, Sam Harwell, All Rights Reserved
</buildStep>
<buildStep step="ValidatingDocumentationSources">
Validating and copying documentation source information
Source: C:\entwickl\...-ts\Development\Main\ECS.NET\ECS.....Interfaces\ECS.....Interfaces.csproj
    Found project &#39;C:\entwickl\...-ts\Development\Main\ECS.NET\ECS.....Interfaces\ECS.....Interfaces.csproj&#39;
Source: C:\entwickl\...-ts\Development\Main\ECS.NET\ECS.....Simulation\ECS.....Simulation.csproj
    Found project &#39;C:\entwickl\...-ts\Development\Main\ECS.NET\ECS.....Simulation\ECS.....Simulation.csproj&#39;
    ...

Parsing project files
    Found assembly &#39;C:\entwickl\...-ts\Development\Main\ECS.NET\ECS.....Interfaces\..\..\...\Win32\Debug\ECS.....Interfaces.dll&#39;
    Found assembly &#39;C:\entwickl\...-ts\Development\Main\ECS.NET\ECS.....Simulation\..\..\...\Win32\Debug\ECS.....Simulation.dll&#39;
    ...

References to include (excluding framework assemblies):
    ...

Copying XML comments files
    C:\entwickl\...-ts\Development\Main\ECS.NET\ECS.....Interfaces\..\..\...\Win32\Debug\ECS.....Interfaces.XML -&gt; C:\entwickl\...-ts\Development\Main\HelpFileLocal\Working\ECS.....Interfaces.XML
    C:\entwickl\...-ts\Development\Main\ECS.NET\ECS.....Simulation\..\..\...\Win32\Debug\ECS.....Simulation.XML -&gt; C:\entwickl\...-ts\Development\Main\HelpFileLocal\Working\ECS.....Simulation.XML
    ...
    
</buildStep>
<buildStep step="GenerateSharedContent">
Generating shared content files (en-US, English (United States))...
<plugIn name="Lightweight Website Style" behavior="After" priority="1000">
</plugIn>    Last step completed in 00:00:00.0120
</buildStep>
<buildStep step="GenerateApiFilter">
Generating API filter for MRefBuilder...
    Last step completed in 00:00:00.0270
</buildStep>
<buildStep step="GenerateReflectionInfo">
Generating reflection information...
[C:\Program Files (x86)\MSBuild\12.0\bin\MSBuild.exe]
Der Buildvorgang wurde am 10.11.2014 15:07:54 gestartet.
Projekt &quot;C:\entwickl\...-ts\Development\Main\HelpFileLocal\Working\GenerateRefInfo.proj&quot; auf Knoten &quot;1&quot; (Standardziele).
PrepareForBuild:
  Das Verzeichnis &quot;obj\Debug\&quot; wird erstellt.
GenerateRefInfo:
  MRefBuilder (v2014.5.31.0)
  Copyright &#184; 2006-2014, Microsoft Corporation, All Rights Reserved.
  Portions Copyright &#184; 2006-2014, Eric Woodruff, All Rights Reserved.
  Loaded 17 assemblies for reflection and 18 dependency assemblies.
  Wrote information on 38 namespaces, 436 types, and 2878 members
  Die Datei wird von &quot;reflection.org&quot; in &quot;reflection.all&quot; kopiert.
  XslTransform (v2014.5.31.0)
  Copyright &#184; 2006-2014, Microsoft Corporation, All Rights Reserved.
  Portions Copyright &#184; 2006-2014, Eric Woodruff, All Rights Reserved.
  Applying XSL transformation &#39;C:\Program Files (x86)\EWSoftware\Sandcastle Help File Builder\ProductionTransforms\MergeDuplicates.xsl&#39;.
Die Erstellung von Projekt &quot;C:\entwickl\...-ts\Development\Main\HelpFileLocal\Working\GenerateRefInfo.proj&quot; ist abgeschlossen (Standardziele).

Der Buildvorgang wurde erfolgreich ausgefhrt.

Verstrichene Zeit 00:00:04.01
    Last step completed in 00:00:04.8160
</buildStep>
<buildStep step="TransformReflectionInfo">
Transforming reflection output...
[C:\Program Files (x86)\MSBuild\12.0\bin\MSBuild.exe]
Der Buildvorgang wurde am 10.11.2014 15:07:58 gestartet.
Projekt &quot;C:\entwickl\...-ts\Development\Main\HelpFileLocal\Working\TransformManifest.proj&quot; auf Knoten &quot;1&quot; (Standardziele).
TransformManifest:
  XslTransform (v2014.5.31.0)
  Copyright &#184; 2006-2014, Microsoft Corporation, All Rights Reserved.
  Portions Copyright &#184; 2006-2014, Eric Woodruff, All Rights Reserved.
  Applying XSL transformation &#39;C:\Program Files (x86)\EWSoftware\Sandcastle Help File Builder\\ProductionTransforms\ApplyVSDocModel.xsl&#39;.
  Die Datei wird von &quot;reflection.xml&quot; in &quot;reflection.nofilenames&quot; kopiert.
  XslTransform (v2014.5.31.0)
  Copyright &#184; 2006-2014, Microsoft Corporation, All Rights Reserved.
  Portions Copyright &#184; 2006-2014, Eric Woodruff, All Rights Reserved.
  Applying XSL transformation &#39;C:\Program Files (x86)\EWSoftware\Sandcastle Help File Builder\ProductionTransforms\AddFilenames.xsl&#39;.
  XslTransform (v2014.5.31.0)
  Copyright &#184; 2006-2014, Microsoft Corporation, All Rights Reserved.
  Portions Copyright &#184; 2006-2014, Eric Woodruff, All Rights Reserved.
  Applying XSL transformation &#39;C:\Program Files (x86)\EWSoftware\Sandcastle Help File Builder\ProductionTransforms\ReflectionToManifest.xsl&#39;.
Die Erstellung von Projekt &quot;C:\entwickl\...-ts\Development\Main\HelpFileLocal\Working\TransformManifest.proj&quot; ist abgeschlossen (Standardziele).

Der Buildvorgang wurde erfolgreich ausgefhrt.

Verstrichene Zeit 00:00:06.96
    Last step completed in 00:00:08.9200
</buildStep>
<buildStep step="GenerateNamespaceSummaries">
Generating namespace summary information...
    Last step completed in 00:00:00.0900
</buildStep>
<buildStep step="GenerateInheritedDocumentation">
Generating inherited documentation...
[C:\Program Files (x86)\MSBuild\12.0\bin\MSBuild.exe]
Sandcastle Help File Builder, version 2014.5.31.0
Copyright &#184; 2006-2014, Eric Woodruff, All Rights Reserved
E-Mail: Eric@EWoodruff.us

Reflection information will be retrieved from &#39;reflection.xml&#39;
Inherited documentation will be written to &#39;_InheritedDocs_.xml&#39;
Indexing C:\Program Files (x86)\Reference Assemblies\Microsoft\Framework\.NETFramework\v4.5\*.xml
Indexing C:\entwickl\...-ts\Development\Main\HelpFileLocal\Working\ECS.....Interfaces.XML
Indexing C:\entwickl\...-ts\Development\Main\HelpFileLocal\Working\ECS.....Simulation.XML
...
Indexed 158858 members in 136 file(s).  17 file(s) to scan for &lt;inheritdoc /&gt; tags.
Merging inherited documentation...

SHFB: Warning GID0004: No comments found for member &#39;M:ECS.....Simulation.HeatTransitionCoefficientCalculatorHxSingleRow.CalculateKaFromHeatFlow(Units.Area,Units.HeatCapacityFlow,Units.HeatCapacityFlow,Units.TemperatureDifference,Units.Power)&#39;
SHFB: Warning GID0004: No comments found for member &#39;M:ECS.....Simulation.HeatTransitionCoefficientCalculatorHxSingleRow.CalculateKaFromNusseltNumber(System.Double,Units.Length,Units.ThermalConductivity)&#39;
SHFB: Warning GID0004: No comments found for member &#39;M:ECS.....Simulation.HeatTransitionCoefficientCalculatorHxSingleRow.CalculateNusseltNumberFromKa(Units.HeatTransitionCoefficient,Units.Length,Units.ThermalConductivity)&#39;
SHFB: Warning GID0004: No comments found for member &#39;M:ECS.....Simulation.HeatTransitionCoefficientCalculatorHxSingleRow.CalculatePhi(Units.HeatCapacityFlow,Units.HeatCapacityFlow,Units.HeatTransitionCoefficient,Units.Area)&#39;
...
Am I getting something wrong?

Kind regards,
Mario
Coordinator
Nov 11, 2014 at 5:08 PM
If you can send me an example that demonstrates the problem, I'll look into it. My e-mail address is in the footer of the pages in the help file.

Eric