Vresions and References

[jcurl]

I appreciate SHFBProject in documenting my OpenSource projects. In these projects, I try to support many different .NET frameworks simultaneously, but not every library I generate supports all the same versions. Some support .NET 10. All support .NET 8.0, 6.0. Some support .NET 4.8, 4.6.2, 4.0.

I'm trying to build a single Help file that tells the user the version which the libraries are targetted to. I had great success with everything supported .NET 8.0, and some supporting .NET framework, because my "main" .shfbproj file just listed all the libraries.

Now, I added just one library with .NET 10.0.

Original "main" .shfbproj file:

<Project ToolsVersion="15.0" DefaultTargets="Build" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
  ...
  <PropertyGroup>
    ...
    <DocumentationSources>
      <!-- ALL PROJECTS REFERENCED HERE -->
      <DocumentationSource sourceFile="..\framework\trace\Trace\bin\$(Configuration)\net8.0\RJCP.Diagnostics.Trace.dll" />
      <DocumentationSource sourceFile="..\framework\trace\Trace\bin\$(Configuration)\net8.0\RJCP.Diagnostics.Trace.xml" />
    </DocumentationSources>
    ...
  </PropertyGroup>
  <PropertyGroup Condition=" '$(Configuration)' == 'Release' ">
    <PlugInConfigurations>
      ...
      <PlugInConfig id="Version Builder" enabled="True">
        <configuration>
          <currentProject label="Net Core" version="8.0, 6.0" ripOldApis="false" />
          <versions>
            <version label="Net Framework" version="4.0" helpFileProject="RJCP.Documentation.net40.shfbproj" />
            <version label="Net Framework" version="4.6.2" helpFileProject="RJCP.Documentation.net462.shfbproj" />
            <version label="Net Framework" version="4.8" helpFileProject="RJCP.Documentation.net48.shfbproj" />
          </versions>
        </configuration>
      </PlugInConfig>

Now, I have only a single project that supports .NET 10. I create a new file RJCP.Documentation.net6.net8.shfbproj that contains all the same projects, and modify the "main" project to reference to the single .NET 10 project I have.

The New "main" file:

<Project ToolsVersion="15.0" DefaultTargets="Build" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
  ...
  <PropertyGroup>
    ...
    <DocumentationSources>
      <!-- ONLY ONE PROJECT NOW -->
      <DocumentationSource sourceFile="..\framework\trace\Trace\bin\$(Configuration)\net10.0\RJCP.Diagnostics.Trace.dll" />
      <DocumentationSource sourceFile="..\framework\trace\Trace\bin\$(Configuration)\net10.0\RJCP.Diagnostics.Trace.xml" />
    </DocumentationSources>
    ...
  </PropertyGroup>
  <PropertyGroup Condition=" '$(Configuration)' == 'Release' ">
    <PlugInConfigurations>
      ...
      <PlugInConfig id="Version Builder" enabled="True">
        <configuration>
          <currentProject label="Net Core" version="10.0" ripOldApis="false" />
          <versions>
            <version label="Net Framework" version="4.0" helpFileProject="RJCP.Documentation.net40.shfbproj" />
            <version label="Net Framework" version="4.6.2" helpFileProject="RJCP.Documentation.net462.shfbproj" />
            <version label="Net Framework" version="4.8" helpFileProject="RJCP.Documentation.net48.shfbproj" />
            <version label="Net Core" version="8.0, 6.0" helpFileProject="RJCP.Documentation.net8.net6.shfbproj" />
          </versions>
        </configuration>
      </PlugInConfig>

When I build, there are many errors generated by RJCP.Documentation.net8.net6.shfbproj where references are no longer found.

warning BE0066: ShowMissingComponent: [M:RJCP.IO.Ports.SerialPortStream.WriteAsync(System.ReadOnlyMemory`1,System.Void)] Missing <summary> documentation [C:\Users\jcurl\Documents\Programming\rjcp.base\RJCP.Documentation\RJCP.Documentation.shfbproj]

Reviewing the generated HTML documentation shows errors, so even though there should be no reference errors in the file RJCP.Documentation.net8.net6.shfbproj (because it is complete), the build generates errors anyway (I suspect because it's not in the main .shfbproj file).

** Test 1 **

If I list all projects from .NET8.0 or .NET10.0 in the "new" .shfbproj, and have only the single project in the .NET8.0 sub project, the warnings go away. But then the version documented is for .NET 10.0 (when it should be only 8.0, 6.0, but clear why this is the case).

This shows .NET 10.0 for APIs, but won't show .NET 8.0, 6.0, even though they were built for this. I can't have the version label with the version "10.0, 8.0, 6.0" as that would show libraries that have only a .NET 8.0 target also being targetted for .NET 10.0.

** Test 2 **

If I list all projects from .NET8.0 or .NET10.0 in the "new" .shfbproj, and have everything repeated in the "subproject" using .NET 8.0 only, the errors return. So I'm not allowed to duplicate the filepaths in the subproject

** Question **

How do I tell SHFB to list the version label for the framework compiled for, if I don't have it for the latest, but only some?

** Workaround **

I don't know of one. The only thing I can do is say, even if I build for .NET 8.0 only, set the version label to "10.0, 8.0, 6.0" and if an API is removed (which I don't have yet), put in a subproject.

[EWSoftware]

Perhaps some of your missing reference issues are because you're using the assembly and XML comments files as documentation sources rather than the projects. If using the project, it should resolve any necessary references and XML comments files related to them and include them in the project. If you're not using the projects because they're multi-targeted, you can specify a specific target framework on the project documentation source.

Version builder was really designed for documenting different versions of the same assembly (assembly version numbers not platforms). Using it to document differing platforms is a hack and has its limitations. Implementing proper platform support like what you see on the Microsoft site (an Applies To section) is planned but it's going to be a while. It will require some fairly significant changes to the build engine. To do it properly, it really needs to group project outputs from documentation sources by target framework, generate reflection data for each of those, and then merge it in a similar fashion to version builder but for target frameworks rather than assembly versions. That gets rid of version builder and solves the current issue of not being able to mix different target framework types (.NET + .NET Framework) within the same set of project documentation sources.