mdoc.targets

<?xml version="1.0" encoding="utf-8"?>
<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">

  <!--
    ============================================================
    SetupMDoc

    Set all the variables needed for mdoc.
    This runs during the build and package phases.
    ============================================================
  -->
  <Target Name="_MDocSetup">
    <PropertyGroup>
      <_ManagedExeLauncher Condition=" '$(OS)' != 'Windows_NT' And Exists ('/Library/Frameworks/Mono.framework/Versions/Current/bin/mono') ">/Library/Frameworks/Mono.framework/Versions/Current/bin/mono</_ManagedExeLauncher>
      <_ManagedExeLauncher Condition=" '$(OS)' != 'Windows_NT' And Exists ('/usr/local/bin/mono') ">/usr/local/bin/mono</_ManagedExeLauncher>
      <_ManagedExeLauncher Condition=" '$(OS)' != 'Windows_NT' And Exists ('/usr/bin/mono') ">/usr/bin/mono</_ManagedExeLauncher>
      <_ManagedExeLauncher Condition=" '$(OS)' != 'Windows_NT' And '$(_ManagedExeLauncher)' == '' ">mono</_ManagedExeLauncher>
      <MDocVersion Condition=" '%(Identity)' == 'mdoc' ">@(PackageReference -> '%(Version)')</MDocVersion>
      <MDocPackagePath Condition=" '%(Name)' == 'mdoc' ">@(PackageDefinitions -> '%(ResolvedPath)')</MDocPackagePath>
      <MDocPackagePath Condition=" '$(MDocPackagePath)' == '' ">$(NuGetPackageRoot)\mdoc\$(MDocVersion)</MDocPackagePath>
      <MDocToolPath>$(MDocPackagePath)\tools\mdoc.exe</MDocToolPath>
      <MDocOutputName>$(TargetName).xml</MDocOutputName>
      <MDocOutputPath>$(TargetDir)$(MDocOutputName)</MDocOutputPath>
      <_ShouldGenerateDocs Condition=" '$(MDocDocumentationDirectory)' != '' and Exists('$(MDocDocumentationDirectory)\index.xml') ">true</_ShouldGenerateDocs>
    </PropertyGroup>
  </Target>

  <!--
    ============================================================
    MDocGenerateDocs

    Generated the XML documentation file using mdoc.
    This runs during the build phase.
    ============================================================
  -->
  <Target Name="MDocGenerateDocs"
          AfterTargets="CoreCompile" DependsOnTargets="_MDocSetup">
    <ItemGroup Condition=" '$(_ShouldGenerateDocs)' == 'true' ">
      <FileWrites Include="$(MDocOutputPath)" />
    </ItemGroup>
    <Exec Condition=" '$(_ShouldGenerateDocs)' == 'true' "
          Command="$(_ManagedExeLauncher) &quot;$(MDocToolPath)&quot; export-msxdoc --debug --out=&quot;$(MDocOutputPath)&quot; &quot;$(MDocDocumentationDirectory)&quot;" />
  </Target>

  <!--
    ============================================================
    MDocAddFilesToPackage

    Make sure the mdoc output goes into the final package.
    This runs during the package phase.
    ============================================================
  -->
  <Target Name="MDocAddFilesToPackage"
          BeforeTargets="_GetBuildOutputFilesWithTfm" DependsOnTargets="_MDocSetup">
    <ItemGroup Condition=" '$(_ShouldGenerateDocs)' == 'true' ">
      <BuildOutputInPackage Include="$(MDocOutputPath)" TargetFramework="$(TargetFramework)" TargetPath="$(MDocOutputName)" />
    </ItemGroup>
  </Target>

  <!--
    ============================================================
    MDocUpdateDocs

    Update the docs in the documentation directory using the
    compiled assemblies.
    This runs as a separate task.
    ============================================================
  -->
  <Target Name="MDocUpdateDocs"
          DependsOnTargets="_MDocSetup">
    <!-- bits for resolving references on Windows -->
    <PropertyGroup Condition=" '$(OS)' == 'Windows_NT' ">
      <FrameworkReferenceAssemblyPath>$(VsInstallRoot)\Common7\IDE\ReferenceAssemblies\Microsoft\Framework</FrameworkReferenceAssemblyPath>
      <WindowsKitsReferenceAssemblyPath>$(MSBuildProgramFiles32)\Windows Kits\10\References\10.0.16299.0</WindowsKitsReferenceAssemblyPath>
    </PropertyGroup>
    <ItemGroup Condition=" '$(OS)' == 'Windows_NT' ">
      <MDocReferenceAssembly Include="$(FrameworkReferenceAssemblyPath)\MonoAndroid\v1.0" />
      <MDocReferenceAssembly Include="$(FrameworkReferenceAssemblyPath)\MonoAndroid\v13.0" />
      <MDocReferenceAssembly Include="$(FrameworkReferenceAssemblyPath)\Xamarin.iOS\v1.0" />
      <MDocReferenceAssembly Include="$(FrameworkReferenceAssemblyPath)\Xamarin.TVOS\v1.0" />
      <MDocReferenceAssembly Include="$(FrameworkReferenceAssemblyPath)\Xamarin.WatchOS\v1.0" />
      <MDocReferenceAssembly Include="$(FrameworkReferenceAssemblyPath)\Xamarin.Mac\v2.0" />
      <MDocReferenceAssembly Include="$(WindowsKitsReferenceAssemblyPath)\Windows.Foundation.FoundationContract\5.0.0.0" />
      <MDocReferenceAssembly Include="$(WindowsKitsReferenceAssemblyPath)\Windows.Foundation.UniversalApiContract\5.0.0.0" />
    </ItemGroup>
    <!-- the actual task -->
    <PropertyGroup>
      <BinConfigDir>$(MSBuildProjectDirectory)\bin\$(Configuration)\</BinConfigDir>
      <TmpDir>$(MSBuildProjectDirectory)\tmp\</TmpDir>
    </PropertyGroup>
    <ItemGroup>
      <MDocReferenceAssembly Include="$(BinConfigDir)monoandroid13.0" />
    </ItemGroup>
    <PropertyGroup>
      <MDocReferenceAssemblies>@(MDocReferenceAssembly -> '--lib=&quot;%(Identity)&quot;', ' ')</MDocReferenceAssemblies>
    </PropertyGroup>
    <RemoveDir Directories="$(TmpDir)" />
    <MakeDir Directories="$(TmpDir)" />
    <Copy SourceFiles="$(MDocDocumentationDirectory)\..\frameworks.xml" DestinationFolder="$(TmpDir)" />
    <Copy SourceFiles="$(BinConfigDir)netstandard2.0\$(AssemblyName).dll" DestinationFolder="$(TmpDir)xamarin-essentials" />
    <Copy SourceFiles="$(BinConfigDir)monoandroid13.0\$(AssemblyName).dll" DestinationFolder="$(TmpDir)xamarin-essentials-android" />
    <Copy SourceFiles="$(BinConfigDir)xamarin.ios10\$(AssemblyName).dll" DestinationFolder="$(TmpDir)xamarin-essentials-ios" />
    <Copy SourceFiles="$(BinConfigDir)xamarin.mac20\$(AssemblyName).dll" DestinationFolder="$(TmpDir)xamarin-essentials-macos" />
    <Copy SourceFiles="$(BinConfigDir)xamarin.tvos10\$(AssemblyName).dll" DestinationFolder="$(TmpDir)xamarin-essentials-tvos" />
    <Copy SourceFiles="$(BinConfigDir)xamarin.watchos10\$(AssemblyName).dll" DestinationFolder="$(TmpDir)xamarin-essentials-watchos" />
    <Copy SourceFiles="$(BinConfigDir)uap10.0.16299\$(AssemblyName).dll" DestinationFolder="$(TmpDir)xamarin-essentials-uwp" />
    <Exec Command="$(_ManagedExeLauncher) &quot;$(MDocToolPath)&quot; update --debug --lang=DocId --delete --frameworks=&quot;$(TmpDir)frameworks.xml&quot; --out=&quot;$(MDocDocumentationDirectory)&quot; $(MDocReferenceAssemblies)" />
    <_FormatDocs DocsRoot="$(MDocDocumentationDirectory)" />
    <_VerifyAllDocsAreComplete DocsRoot="$(MDocDocumentationDirectory)" />
  </Target>

  <!--
    ============================================================
    MDocVerifyDocs

    Makes sure all the docs are filled in.
    This runs as a separate task.
    ============================================================
  -->
  <Target Name="MDocVerifyDocs"
          DependsOnTargets="_MDocSetup">
    <_FormatDocs DocsRoot="$(MDocDocumentationDirectory)" />
    <_VerifyAllDocsAreComplete DocsRoot="$(MDocDocumentationDirectory)" />
  </Target>

  <!--
    ===================================================================================================================
    _FormatDocs

    Make sure the docs are all uniform after editing in various apps or tools.
    ===================================================================================================================
  -->
  <UsingTask TaskName="_FormatDocs" TaskFactory="CodeTaskFactory" AssemblyFile="$(MSBuildToolsPath)\Microsoft.Build.Tasks.Core.dll" >  
    <ParameterGroup>
      <DocsRoot ParameterType="System.String" />
    </ParameterGroup>
    <Task>
      <Reference Include="System.Xml" />
      <Reference Include="System.Xml.Linq" />
      <Using Namespace="System.Xml" />
      <Using Namespace="System.Xml.Linq" />
      <Code Type="Fragment" Language="cs"><![CDATA[
        foreach (var file in Directory.EnumerateFiles(DocsRoot, "*.xml", SearchOption.AllDirectories)) {
          var xdoc = XDocument.Load(file);

          // special case for Android resources: don't process
          if (xdoc.Root.Name == "Type") {
            var nameAttr = xdoc.Root.Attribute("FullName");
            if (nameAttr != null && (nameAttr.Value == "Xamarin.Essentials.Resource" || nameAttr.Value.StartsWith("Xamarin.Essentials.Resource+"))) {
              File.Delete(file);
              continue;
            }
          }
          if (xdoc.Root.Name == "Overview") {
            foreach (var type in xdoc.Root.Descendants("Type").ToArray()) {
              var nameAttr = type.Attribute("Name");
              if (nameAttr != null && (nameAttr.Value == "Resource" || nameAttr.Value.StartsWith("Resource+"))) {
                type.Remove();
              }
            }
          }
          if (xdoc.Root.Name == "Framework") {
            foreach (var type in xdoc.Root.Descendants("Type").ToArray()) {
              var nameAttr = type.Attribute("Name");
              if (nameAttr != null && (nameAttr.Value == "Xamarin.Essentials.Resource" || nameAttr.Value.StartsWith("Xamarin.Essentials.Resource/"))) {
                type.Remove();
              }
            }
          }

          // the tooling can't handle the ToPlatform* that differs only on return types
          if (xdoc.Root.Name == "Type") {
            var typeNameAttr = xdoc.Root.Attribute("FullName");
            if (typeNameAttr != null && typeNameAttr.Value.EndsWith("Extensions")) {
              foreach (var member in xdoc.Root.Descendants("Member").ToArray()) {
                var memberNameAttr = member.Attribute("MemberName");
                if (memberNameAttr != null && memberNameAttr.Value.StartsWith("ToPlatform")) {
                  member.Remove();
                }
              }
            }
          }
          if (xdoc.Root.Name == "Overview") {
            foreach (var member in xdoc.Root.Descendants("Member").ToArray()) {
              var memberNameAttr = member.Attribute("MemberName");
              if (memberNameAttr != null && memberNameAttr.Value.StartsWith("ToPlatform")) {
                member.Remove();
              }
            }
          }
          if (xdoc.Root.Name == "Framework") {
            foreach (var type in xdoc.Root.Descendants("Type").ToArray()) {
              var typeNameAttr = type.Attribute("Name");
              if (typeNameAttr != null && typeNameAttr.Value.EndsWith("Extensions")) {
                foreach (var member in type.Descendants("Member").ToArray()) {
                  var memberNameAttr = member.Attribute("Id");
                  if (memberNameAttr != null && memberNameAttr.Value.Contains(".ToPlatform")) {
                    member.Remove();
                  }
                }
              }
            }
          }

          var settings = new XmlWriterSettings {
              Encoding = new UTF8Encoding(),
              Indent = true,
              NewLineChars = "\n",
              OmitXmlDeclaration = true,
          };
          using (var writer = XmlWriter.Create(file, settings)) {
              xdoc.Save(writer);
              writer.Flush();
          }
          File.AppendAllText(file, "\n");
        }
      ]]></Code>
    </Task>
  </UsingTask>

  <!--
    ===================================================================================================================
    _VerifyAllDocsAreComplete

    Make sure the docs are all filled in.
    ===================================================================================================================
  -->
  <UsingTask TaskName="_VerifyAllDocsAreComplete" TaskFactory="CodeTaskFactory" AssemblyFile="$(MSBuildToolsPath)\Microsoft.Build.Tasks.Core.dll" >  
    <ParameterGroup>
      <DocsRoot ParameterType="System.String" />
    </ParameterGroup>
    <Task>
      <Reference Include="System.Xml" />
      <Reference Include="System.Xml.Linq" />
      <Using Namespace="System.IO" />
      <Using Namespace="System.Xml" />
      <Using Namespace="System.Xml.Linq" />
      <Code Type="Fragment" Language="cs"><![CDATA[
        foreach (var file in Directory.EnumerateFiles(DocsRoot, "*.xml", SearchOption.AllDirectories)) {
          var xdoc = XDocument.Load(file);
          var incomplete = xdoc.Descendants("Docs").Where(x => x.Descendants().Any(d => d.Value == "To be added."));
          foreach (var node in incomplete) {
            if (node.Parent.Name == "Type" && xdoc.Root.Name == "Type") {
              var typename = xdoc.Root.Attribute("FullName").Value;
              Log.LogWarning("Missing docs for {0}.", typename);
            } else if (node.Parent.Name == "Member" && xdoc.Root.Name == "Type") {
              var typename = xdoc.Root.Attribute("FullName").Value;
              var member = node.Parent.Attribute("MemberName").Value;
              var memberType = node.Parent.Element("MemberType").Value.ToLower();
              Log.LogWarning("Missing docs for {2} '{0}.{1}'.", typename, member, memberType);
            } else {
              Log.LogWarning("Missing docs in {0}.", file);
            }
          }
        }
      ]]></Code>
    </Task>
  </UsingTask>

</Project>