Add new PackageReference options to discriminate between compiled and documentation files

[IanKemp]

NuGet Product(s) Involved

dotnet.exe

The Elevator Pitch

We have a package consumed internally by our organisation that exposes some functionality that includes utility methods. Recently we have discovered a third-party package that implements some of these utilities in a better way than ours, as well as offering some others we were thinking about adding, so we want to wrap and bundle that package with ours, and simply delegate our methods to call into that package.

However, we do not want consumers of our internal package to be able to access the methods in the third-party package, because some of the methods it provides are not relevant or could cause incorrect behaviour if called in isolation. Thus we have set that package's reference to be PrivateAssets="compile" in our .csproj.

For the new methods we were going to add, that already exist in the third-party package, we've done this:

<inheritdoc cref="ThirdPartyPackageNamespace.ThirdPartyPackageClass.DoSomething(OtherBclType, AThirdBclType)" />
public static SomeBclType DoSomething(OtherBclType foo, AThirdBclType bar)
    => ThirdPartyPackageNamespace.ThirdPartyPackageClass.DoSomething(foo, bar);

However, due to the fact that package documentation is contained in the lib folder next to its DLL, and that we've set PrivateAssets="compile", the third-party package's documentation isn't included when our package is built. In other words, the <inheritdoc> elements have no effect and consumers of our package see no docs.

What is needed are two new options for PrivateAssets:

• compiledOnly - applies to only DLLs in lib and its subdirectories
• documentationOnly - applies to only documentation files in lib and its subdirectories

In our case we would then use PrivateAssets="compiledOnly". Further, compile would be reworked to effectively be the same as compiledOnly;documentationOnly.

Additional Context and Details

No response