Libraries nuget packages contain XML docs next to runtime assemblies

[ericstj]

Noticed this with System.DirectoryServices.Protocols:

system.directoryservices.protocols\4.7.0\lib\netstandard2.0\System.DirectoryServices.Protocols.xml
system.directoryservices.protocols\4.7.0\ref\netstandard2.0\System.DirectoryServices.Protocols.xml
system.directoryservices.protocols\4.7.0\runtimes\win\lib\netcoreapp2.0\System.DirectoryServices.Protocols.xml

Both the lib and runtimes xml's will never be used.

[ericstj]

This was regressed with dotnet/corefx#32934 @AraHaan @danmosemsft

This set DocumentationFile for all src projects:
https://github.com/dotnet/corefx/pull/32934/files#diff-4b2f402501d23abbede6eac0f47783e4R472

We use the value of this to determine if a src project should include docs:
https://github.com/dotnet/arcade/blob/e0396581483c2355dcc22fb433c4f3a95a01ad5b/src/Microsoft.DotNet.Build.Tasks.Packaging/src/build/PackageLibs.targets#L43-L44

We still will prefer a centrally defined doc from our docs package, so we don't end up using the incomplete source-generated docs files.
https://github.com/dotnet/arcade/blob/e0396581483c2355dcc22fb433c4f3a95a01ad5b/src/Microsoft.DotNet.Build.Tasks.Packaging/src/build/PackageLibs.targets#L169-L184

We need to either undo that property or change how we calculate whether or not to include docs.

This change bloated most packages that have ref and src considerably.

@carlossanlop @safern @joperezr

[AraHaan]

I personally like the docs to be in the ref and the lib dirs because then projects that depend on them sometimes copies them over to the published copy so then those who want to see what a library does can read them.

Especially when their project does not have any website that hosts their documentations or does not even use the github wiki to document it either (or the wiki is incomplete because of lack of motivation) or control of syncing the xml doc comments to it. Maybe one day github will get smart enough that on c# repositories auto generate a documentation wiki page which auto updates based on the xml doc comments in their code on their repository (when set to do so as a setting).

[joperezr]

If/When we do this, we will have to make sure we consider the case where ExcludeReferenceAssets is set to true, because we will want to include the xmls in that case as the lib asset will be the one that the compilers will get and will need to be documented.

[ericstj]

I personally like the docs to be in the ref and the lib dirs because then projects that depend on them sometimes copies them over to the published copy so then those who want to see what a library does can read them.

The behavior you describe is an artifact of the old MSBuild non-transitive references. This was done because otherwise you'd never see the assets from a transitive reference. With NuGet + PackageReference this shouldn't be an issue, since projects will always receive the transitive reference, and thus the XML from the package itself.

@joperezr good point, and something we'd want to check when doing this work. I believe this was working correctly in 2.x when we had some similar concerns, but I could be wrong.