Skip to content

Enable publishing XML documentation #1062

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Apr 11, 2017
Merged

Enable publishing XML documentation #1062

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
1afbf31
Publish XML documentaiton by default and enable opting out of publisi…
dasMulli Apr 3, 2017
56d9419
Renamed PublishProjectReferenceDocumentationFiles to PublishReference…
dasMulli Apr 6, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 9 additions & 1 deletion src/Tasks/Microsoft.NET.Build.Tasks/build/Microsoft.NET.Publish.targets
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -201,6 +201,12 @@ Copyright (c) .NET Foundation. All rights reserved.
<ResolvedFileToPublish Include="@(ResolvedAssembliesToPublish)">
<RelativePath>%(ResolvedAssembliesToPublish.DestinationSubPath)</RelativePath>
</ResolvedFileToPublish>

<!-- Copy the xml documentation (if enabled) -->
<ResolvedFileToPublish Include="@(FinalDocFile)"
Condition="'$(PublishDocumentationFile)' == 'true'">
<RelativePath>@(FinalDocFile->'%(Filename)%(Extension)')</RelativePath>
</ResolvedFileToPublish>
</ItemGroup>

</Target>
Expand All @@ -211,7 +217,9 @@ Copyright (c) .NET Foundation. All rights reserved.
<!-- TODO perform any preprocess transforms on the files -->

<ItemGroup>
<ResolvedAssembliesToPublish Include="@(ReferenceCopyLocalPaths)" Exclude="@(ResolvedAssembliesToPublish)">
<ResolvedAssembliesToPublish Include="@(ReferenceCopyLocalPaths)"
Exclude="@(ResolvedAssembliesToPublish)"
Condition="'$(PublishProjectReferenceDocumentationFiles)' == 'true' or '%(Extension)' != '.xml'">
Copy link
Member

@eerhardt eerhardt Apr 4, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@rainersigwald @cdmihai @KirillOsenkov @jeffkl - are documentation files the only type of xml files that can get put in @(ReferenceCopyLocalPaths)? Is there some other way to distinguish what is a P2P reference's doc file?

I'm not sure who else would know this, maybe @ericstj @weshaggard @davkean ...?

Copy link
Contributor

@jeffkl jeffkl Apr 4, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Here's how the documentation file works:

  1. It starts life as a property <DocumentationFile /> defined in an individual project
  2. It gets added to an item group @(DocFileItem) here
  3. @(DocFileItem) is passed to <Csc /> here
  4. It is added an item group @(FinalDocFile) here which is a full path to where the file should be copied to
  5. The @(DocFileItem) is copied to @(FinalDocFile) here
  6. <ResolveAssemblyReference /> gets passed a list of related file extensions which includes .xml.

So technically, the only reason the Doc file shows up in @(ReferenceCopyLocalPaths) is because it has the same file name without extension as the output assembly. This logic takes the output file name and looks for "related" files by extensions, one of which is .xml. If people were trying to be fancy, they could have their documentation file named something else and it would show up in @(ReferenceCopyLocalPaths).

That said, it's probably safe to assume that the only related file ending in .xml is the doc file. MSBuild does not currently translate any metadata to these related files that indicate what they were originally.

<DestinationSubPath>%(ReferenceCopyLocalPaths.DestinationSubDirectory)%(Filename)%(Extension)</DestinationSubPath>
</ResolvedAssembliesToPublish>
</ItemGroup>
Expand Down
6 changes: 6 additions & 0 deletions src/Tasks/Microsoft.NET.Build.Tasks/build/Microsoft.NET.Sdk.BeforeCommon.targets
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -137,6 +137,12 @@ Copyright (c) .NET Foundation. All rights reserved.
<DocumentationFile />
</PropertyGroup>

<PropertyGroup>
<PublishDocumentationFiles Condition="'$(PublishDocumentationFiles)' == ''">true</PublishDocumentationFiles>
<PublishDocumentationFile Condition="'$(PublishDocumentationFile)' == '' and '$(PublishDocumentationFiles)' == 'true'">true</PublishDocumentationFile>
<PublishProjectReferenceDocumentationFiles Condition="'$(PublishProjectReferenceDocumentationFiles)' == '' and '$(PublishDocumentationFiles)' == 'true'">true</PublishProjectReferenceDocumentationFiles>
</PropertyGroup>

<!-- Add a project capability so that the project properties in the IDE can show the option to generate an XML documentation file without specifying the filename -->
<ItemGroup>
<ProjectCapability Include="GenerateDocumentationFile" />
Expand Down
49 changes: 49 additions & 0 deletions test/Microsoft.NET.Publish.Tests/GivenThatWeWantToPublishAProjectWithDependencies.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,7 @@
using System.Runtime.InteropServices;
using Newtonsoft.Json;
using Newtonsoft.Json.Linq;
using System.Collections.Generic;

namespace Microsoft.NET.Publish.Tests
{
Expand Down Expand Up @@ -195,6 +196,54 @@ public void It_publishes_projects_with_filter_and_rid()

//TODO: Enable testing the run once dotnet host has the notion of looking up shared packages
}


[Theory]
[MemberData(nameof(PublishDocumentationExpectations))]
Copy link
Contributor

@livarcocc livarcocc Apr 6, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why use member data here and inlinedata in the other? I particularly prefer inlinedata in this case.

Copy link
Contributor Author

@dasMulli dasMulli Apr 6, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Rule of thumb.. 4x3 arguments was more than 2x2.
But you're right, even other tests use InlineData more. I'll change it.

public void It_publishes_documentation_files(string properties, bool expectAppDocPublished, bool expectLibDocPublished)
{
var kitchenSinkAsset = _testAssetsManager
.CopyTestAsset("KitchenSink")
.WithSource();
kitchenSinkAsset.Restore("TestApp");

var publishCommand = new PublishCommand(Stage0MSBuild, Path.Combine(kitchenSinkAsset.TestRoot, "TestApp"));
var publishResult = publishCommand.Execute(properties);

publishResult.Should().Pass();

var publishDirectory = publishCommand.GetOutputDirectory();

if (expectAppDocPublished)
{
publishDirectory.Should().HaveFile("TestApp.xml");
}
else
{
publishDirectory.Should().NotHaveFile("TestApp.xml");
}

if (expectLibDocPublished)
{
publishDirectory.Should().HaveFile("TestLibrary.xml");
}
else
{
publishDirectory.Should().NotHaveFile("TestLibrary.xml");
}
}

public static IEnumerable<object[]> PublishDocumentationExpectations
{
get
{
yield return new object[] { "/p:GenerateDocumentationFile=true", true, true };
yield return new object[] { "/p:GenerateDocumentationFile=true;PublishDocumentationFile=false", false, true };
yield return new object[] { "/p:GenerateDocumentationFile=true;PublishProjectReferenceDocumentationFiles=false", true, false };
yield return new object[] { "/p:GenerateDocumentationFile=true;PublishDocumentationFiles=false", false, false };
}
}

private static JObject ReadJson(string path)
{
using (JsonTextReader jsonReader = new JsonTextReader(File.OpenText(path)))
Expand Down