Merge pull request #664 from mono/develop

bump mdoc to 5.9.2.1
mono · Feb 7, 2023 · a18cba5 · a18cba5
2 parents f21c774 + 2a71fe9
commit a18cba5
Show file tree

Hide file tree

Showing 9 changed files with 94 additions and 52 deletions.
diff --git a/.config/tsaoptions.json b/.config/tsaoptions.json
@@ -0,0 +1,10 @@
+{
+  "instanceUrl": "https://ceapex.visualstudio.com",
+  "projectName": "Engineering",
+  "areaPath": "Engineering\\Reference",
+  "iterationPath": "Engineering",
+  "notificationAliases": [ "[email protected]", "[email protected]" ],
+  "template": "TFSMSAzure",
+  "repositoryName": "api-doc-tools",
+  "codebaseName": "Docs_Mdoc"
+}
diff --git a/azure-pipelines.lgtm.yml b/azure-pipelines.lgtm.yml
@@ -17,10 +17,15 @@ pool:
 
 variables:
   Codeql.Enabled: true
+  Codeql.TSAEnabled: true
   solution: 'apidoctools.sln'
   buildConfiguration: 'Release'
 
 steps:
+- task: CodeQL3000Init@0
+  inputs:
+    Enabled: true  
+
 - task: CmdLine@2
   displayName: make prepare
   inputs:
@@ -31,3 +36,7 @@ steps:
   inputs:
     solution: '$(solution)'
     configuration: '$(buildConfiguration)'
+
+- task: CodeQL3000Finalize@0
+  inputs:
+    Enabled: true
diff --git a/mdoc/Consts.cs b/mdoc/Consts.cs
@@ -3,7 +3,7 @@ namespace Mono.Documentation
 {
     public static class Consts
     {
-        public static string MonoVersion = "5.9.2";
+        public static string MonoVersion = "5.9.2.1";
         public const string DocId = "DocId";
         public const string CppCli = "C++ CLI";
         public const string CppCx = "C++ CX";

diff --git a/mdoc/Makefile b/mdoc/Makefile
@@ -210,7 +210,7 @@ Test/FrameworkTestData: Test/DocTest-addNonGeneric.dll Test/DocTest-DropNS-class
 	cp Test/DocTest-DropNS-classic.dll Test/FrameworkTestData/One/
 	cp Test/DocTest-addNonGeneric.dll Test/FrameworkTestData/Two/
 	cp Test/DocTest-DropNS-classic-secondary.dll Test/FrameworkTestData/Two/
-	$(MONO) $(PROGRAM) fx-bootstrap Test/FrameworkTestData
+	$(MONO) $(PROGRAM) fx-bootstrap -fx Test/FrameworkTestData
 
 Test/FrameworkTestData-fx-inheritance: Test/DocTest-framework-inheritance-one.dll Test/DocTest-framework-inheritance-two.dll Test/DocTest-framework-inheritance-three.dll
 	rm -rf Test/FrameworkTestData-fx-inheritance
@@ -221,7 +221,7 @@ Test/FrameworkTestData-fx-inheritance: Test/DocTest-framework-inheritance-one.dl
 	cp Test/DocTest-framework-inheritance-one.dll Test/FrameworkTestData-fx-inheritance/One/
 	cp Test/DocTest-framework-inheritance-two.dll Test/FrameworkTestData-fx-inheritance/Two/
 	cp Test/DocTest-framework-inheritance-three.dll Test/FrameworkTestData-fx-inheritance/Three/
-	$(MONO) $(PROGRAM) fx-bootstrap Test/FrameworkTestData-fx-inheritance
+	$(MONO) $(PROGRAM) fx-bootstrap -fx Test/FrameworkTestData-fx-inheritance
 
 .PHONY: check-monodocer-differentTypeDefinitions
 check-monodocer-differentTypeDefinitions : Test/DocTest-differentTypeDefinitions-First.dll Test/DocTest-differentTypeDefinitions-Second.dll
@@ -232,7 +232,7 @@ check-monodocer-differentTypeDefinitions : Test/DocTest-differentTypeDefinitions
 	mkdir Test/FrameworkTestData-fx-differentTypeDefinitions/One
 	cp Test/DocTest-differentTypeDefinitions-First.dll Test/FrameworkTestData-fx-differentTypeDefinitions/One
 	cp Test/DocTest-differentTypeDefinitions-Second.dll Test/FrameworkTestData-fx-differentTypeDefinitions/One
-	$(MONO) $(PROGRAM) fx-bootstrap Test/FrameworkTestData-fx-differentTypeDefinitions
+	$(MONO) $(PROGRAM) fx-bootstrap -fx Test/FrameworkTestData-fx-differentTypeDefinitions
 
 	$(MONO) $(PROGRAM) update -o Test/en.actual -frameworks Test/FrameworkTestData-fx-differentTypeDefinitions
 	$(DIFF) Test/en.expected.differentTypeDefinitions Test/en.actual
@@ -247,7 +247,7 @@ check-monodocer-differentTypeParameterNames : Test/DocTest-differentTypeParamete
 	mkdir Test/FrameworkTestData-fx-differentTypeParameterNames/Two
 	cp Test/DocTest-differentTypeParameterNames-First.dll Test/FrameworkTestData-fx-differentTypeParameterNames/One
 	cp Test/DocTest-differentTypeParameterNames-Second.dll Test/FrameworkTestData-fx-differentTypeParameterNames/Two
-	$(MONO) $(PROGRAM) fx-bootstrap Test/FrameworkTestData-fx-differentTypeParameterNames
+	$(MONO) $(PROGRAM) fx-bootstrap -fx Test/FrameworkTestData-fx-differentTypeParameterNames
 
 	$(MONO) $(PROGRAM) update -o Test/en.actual -frameworks Test/FrameworkTestData-fx-differentTypeParameterNames
 	$(DIFF) Test/en.expected.differentTypeParameterNames Test/en.actual
@@ -281,7 +281,7 @@ check-monodocer-typeForwards : Test/DocTest-typeForwards-First.dll Test/DocTest-
 	cp Test/DocTest-typeForwards-Third-First.dll Test/FrameworkTestData-fx-typeForwards/Three
 	cp Test/DocTest-typeForwards-Second.dll Test/FrameworkTestData-fx-typeForwards/dependencies/Three
 	cp Test/DocTest-typeForwards-Third.dll Test/FrameworkTestData-fx-typeForwards/dependencies/Three
-	$(MONO) $(PROGRAM) fx-bootstrap Test/FrameworkTestData-fx-typeForwards
+	$(MONO) $(PROGRAM) fx-bootstrap -fx Test/FrameworkTestData-fx-typeForwards
 
 	# now run mdoc update
 	$(MONO) $(PROGRAM) update -o Test/en.actual -frameworks Test/FrameworkTestData-fx-typeForwards
@@ -312,7 +312,7 @@ check-monodocer-nestedType-typeForwards : Test/DocTest-nestedType-typeForwards-F
 	cp Test/DocTest-nestedType-typeForwards-Third-First.dll Test/FrameworkTestData-fx-nestedType-typeForwards/Three
 	cp Test/DocTest-nestedType-typeForwards-Second.dll Test/FrameworkTestData-fx-nestedType-typeForwards/dependencies/Three
 	cp Test/DocTest-nestedType-typeForwards-Third.dll Test/FrameworkTestData-fx-nestedType-typeForwards/dependencies/Three
-	$(MONO) $(PROGRAM) fx-bootstrap Test/FrameworkTestData-fx-nestedType-typeForwards
+	$(MONO) $(PROGRAM) fx-bootstrap -fx Test/FrameworkTestData-fx-nestedType-typeForwards
 
 	# now run mdoc update
 	$(MONO) $(PROGRAM) update -o Test/en.actual -frameworks Test/FrameworkTestData-fx-nestedType-typeForwards
@@ -697,7 +697,7 @@ Test/FrameworkTestData-frameworkalternate: Test/DocTest-frameworkalternate-one.d
 	cp Test/DocTest-frameworkalternate-one.dll Test/FrameworkTestData-frameworkalternate/One/
 	cp Test/DocTest-frameworkalternate-two.dll Test/FrameworkTestData-frameworkalternate/Two/
 	cp Test/DocTest-frameworkalternate-one.dll Test/FrameworkTestData-frameworkalternate/Three/
-	$(MONO) $(PROGRAM) fx-bootstrap Test/FrameworkTestData-frameworkalternate
+	$(MONO) $(PROGRAM) fx-bootstrap -fx Test/FrameworkTestData-frameworkalternate
 
 .PHONY: Test/FrameworkTestData-frameworkalternate-fromold
 Test/FrameworkTestData-frameworkalternate-fromold: Test/DocTest-frameworkalternate-one.dll Test/DocTest-frameworkalternate-two.dll
@@ -709,7 +709,7 @@ Test/FrameworkTestData-frameworkalternate-fromold: Test/DocTest-frameworkalterna
 	cp Test/DocTest-frameworkalternate-one.dll Test/FrameworkTestData-frameworkalternate-fromold/One/
 	cp Test/DocTest-frameworkalternate-two.dll Test/FrameworkTestData-frameworkalternate-fromold/Two/
 	cp Test/DocTest-frameworkalternate-one.dll Test/FrameworkTestData-frameworkalternate-fromold/Three/
-	$(MONO) $(PROGRAM) fx-bootstrap Test/FrameworkTestData-frameworkalternate-fromold
+	$(MONO) $(PROGRAM) fx-bootstrap -fx Test/FrameworkTestData-frameworkalternate-fromold
 
 Test/DocTest-frameworkalternate-one.dll: 
 	$(CSCOMPILE) $(TEST_CSCFLAGS) -debug -target:library -out:$@ Test/DocTest-frameworkalternate.cs /define:FXONE
@@ -897,7 +897,7 @@ check-type-projection: Test/DocTest-TypeProjection.dll
 	cp Test/TestTypeMap.xml Test/test-type-projection/
 	mv Test/test-type-projection/TestTypeMap.xml Test/test-type-projection/TypeMap.xml
 
-	$(MONO) $(PROGRAM) fx-bootstrap Test/test-type-projection
+	$(MONO) $(PROGRAM) fx-bootstrap -fx Test/test-type-projection
 	$(MONO) $(PROGRAM) update -fx Test/test-type-projection/ -o Test/en.actual/
 	$(DIFF) Test/en.expected-type-projection Test/en.actual/
 
@@ -911,7 +911,7 @@ check-long-file-name: Test/DocTest-LongFileName.dll
 
 	cp Test/DocTest-LongFileName.dll Test/test-long-file-name/DocTest-LongFileName
 
-	$(MONO) $(PROGRAM) fx-bootstrap Test/test-long-file-name
+	$(MONO) $(PROGRAM) fx-bootstrap -fx Test/test-long-file-name
 	$(MONO) $(PROGRAM) update -fx Test/test-long-file-name -o Test/en.actual/
 
 run-test-local: check-doc-tools

diff --git a/mdoc/Mono.Documentation/MDocUpdater.cs b/mdoc/Mono.Documentation/MDocUpdater.cs
@@ -990,10 +990,10 @@ private void AddIndexAssembly (AssemblyDefinition assembly, XmlElement parent, F
             {
                 XmlElement pubkey = WriteElement (index_assembly, "AssemblyPublicKey");
                 var key = new StringBuilder (name.PublicKey.Length * 3 + 2);
-                key.Append ("[");
+                key.Append ('[');
                 foreach (byte b in name.PublicKey)
                     key.AppendFormat ("{0,2:x2} ", b);
-                key.Append ("]");
+                key.Append (']');
                 pubkey.InnerText = key.ToString ();
                 index_assembly.AppendChild (pubkey);
             }
@@ -1267,7 +1267,7 @@ public override int Compare (XmlNode x, XmlNode y)
 
             static string GetVersion (string v)
             {
-                int n = v.IndexOf ("x");
+                int n = v.IndexOf ('x');
                 if (n < 0)
                     return v;
                 return v.Substring (0, n - 1);
@@ -1999,20 +1999,22 @@ class MemberComparer : XmlNodeComparer
             public override int Compare (XmlNode x, XmlNode y)
             {
                 int r;
-                string xMemberName = x.Attributes["MemberName"].Value;
-                string yMemberName = y.Attributes["MemberName"].Value;
+                string xFullMemberName = x.Attributes["MemberName"].Value;
+                string yFullMemberName = y.Attributes["MemberName"].Value;
+                string xMemberName = xFullMemberName;
+                string yMemberName = yFullMemberName;
 
                 // generic methods *end* with '>'
                 // it's possible for explicitly implemented generic interfaces to
                 // contain <...> without being a generic method
-                if ((!xMemberName.EndsWith (">") || !yMemberName.EndsWith (">")) &&
+                if ((!xMemberName.EndsWith (">", StringComparison.Ordinal) || !yMemberName.EndsWith (">", StringComparison.Ordinal)) &&
                         (r = xMemberName.CompareTo (yMemberName)) != 0)
                     return r;
 
                 int lt;
-                if ((lt = xMemberName.IndexOf ("<")) >= 0)
+                if ((lt = xMemberName.IndexOf ('<')) >= 0)
                     xMemberName = xMemberName.Substring (0, lt);
-                if ((lt = yMemberName.IndexOf ("<")) >= 0)
+                if ((lt = yMemberName.IndexOf ('<')) >= 0)
                     yMemberName = yMemberName.Substring (0, lt);
                 if ((r = xMemberName.CompareTo (yMemberName)) != 0)
                     return r;
@@ -2075,7 +2077,7 @@ public override int Compare (XmlNode x, XmlNode y)
                         return r;
                 }
 
-                return 0;
+                return xFullMemberName.CompareTo(yFullMemberName);
             }
         }
 
@@ -4186,7 +4188,7 @@ private void MakeParameters (XmlElement root, MemberReference mi, FrameworkTypeE
 
         public static string GetDocParameterType (TypeReference type, bool useTypeProjection = false)
         {
-            var typename = GetDocTypeFullName (type, useTypeProjection).Replace ("@", "&");
+            var typename = GetDocTypeFullName (type, useTypeProjection).Replace ('@', '&');
 
             if (useTypeProjection || string.IsNullOrEmpty(typename))
             {
@@ -4337,11 +4339,11 @@ private static void AddGenericParameter(StringBuilder sb, MethodDefinition mb)
                 IList<GenericParameter> typeParams = mb.GenericParameters;
                 if (typeParams.Count > 0)
                 {
-                    sb.Append("<");
+                    sb.Append('<');
                     sb.Append(typeParams[0].Name);
                     for (int i = 1; i < typeParams.Count; ++i)
-                        sb.Append(",").Append(typeParams[i].Name);
-                    sb.Append(">");
+                        sb.Append(',').Append(typeParams[i].Name);
+                    sb.Append('>');
                 }
             }
         }
@@ -4420,7 +4422,7 @@ internal static string GetXPathForMember (DocumentationMember member)
                 {
                     xpath.Append (" and Parameter [").Append (i + 1).Append ("]/@Type=\"");
                     xpath.Append (member.Parameters[i]);
-                    xpath.Append ("\"");
+                    xpath.Append ('"');
                 }
                 xpath.Append ("]/..");
             }
@@ -4447,7 +4449,7 @@ public static string GetXPathForMember (XPathNavigator member)
                     ++i;
                     xpath.Append (" and Parameter [").Append (i).Append ("]/@Type=\"");
                     xpath.Append (parameters.Current.Value);
-                    xpath.Append ("\"");
+                    xpath.Append ('"');
                 }
                 xpath.Append ("]/..");
             }
@@ -4479,7 +4481,7 @@ public static string GetXPathForMember (MemberReference member)
                 {
                     xpath.Append (" and Parameter [").Append (i + 1).Append ("]/@Type=\"");
                     xpath.Append (GetDocParameterType (parameters[i].ParameterType));
-                    xpath.Append ("\"");
+                    xpath.Append ('"');
                 }
                 xpath.Append ("]/..");
             }

diff --git a/mdoc/Mono.Documentation/Updater/Formatters/AttributeFormatters/AttributeFormatter.cs b/mdoc/Mono.Documentation/Updater/Formatters/AttributeFormatters/AttributeFormatter.cs
@@ -138,14 +138,23 @@ private bool IsIgnoredAttribute(CustomAttribute customAttribute)
                 return false;
             }
 
-            var attrTypeDef = attrType as TypeDefinition;
-            if (attrTypeDef != null && !DocUtils.IsPublic(attrTypeDef) || (FormatterManager.SlashdocFormatter.GetName(attrType) == null)
+            if (FormatterManager.SlashdocFormatter.GetName(attrType) == null
                 || Array.IndexOf(IgnorableAttributes, attrType.FullName) >= 0)
             {
                 return true;
             }
 
-            return false;
+            try
+            {
+                var attrTypeDef = attrType.Resolve();
+                // We probably should return true if attrTypeDef is null, but it would cause too many diffs in dotnet-api-docs repo.
+                return attrTypeDef != null && !DocUtils.IsPublic(attrTypeDef);
+            }
+            catch (Exception ex)
+            {
+                Console.WriteLine($"Unable to resolve {attrType.FullName}", ex);
+                return true;
+            }
         }
 
         // FIXME: get TypeReferences instead of string comparison?

diff --git a/mdoc/Mono.Documentation/frameworksbootstrapper.cs b/mdoc/Mono.Documentation/frameworksbootstrapper.cs
@@ -13,13 +13,23 @@ namespace Mono.Documentation
 {
 	public class MDocFrameworksBootstrapper : MDocCommand
 	{
+		private string frameworkPath;
+        private bool importContent = true;
+
 		public override void Run (IEnumerable<string> args)
 		{
-			args = args.Skip (1);
-			if (args.Count () != 1)
-				Error ("Need to supply a single directory, which contain folders that represent frameworks.");
+			var option = new OptionSet()
+			{
+				{ "fx|frameworks=", "Directories which contain libraries that span multiple frameworks.", v => frameworkPath = v },
+				{ "importContent=", "Import XML Comment files to frameworks.xml.", v => bool.TryParse(v, out importContent) }
+			};
+
+            option.Parse(args);
+            if (string.IsNullOrWhiteSpace(frameworkPath))
+			{
+                Error("Framework Path should not be null or empty.");
+            }
 
-			string frameworkPath = args.Single ();
 			int slashOffset = frameworkPath.EndsWith (Path.DirectorySeparatorChar.ToString (), StringComparison.InvariantCultureIgnoreCase) ? 0 : 1;
 
 			if (!Directory.Exists(frameworkPath)) 
@@ -64,20 +74,23 @@ public override void Run (IEnumerable<string> args)
 								 new XElement("assemblySearchPath", Path.Combine("dependencies", d.Name))));
 			}
 
-			var maxVersions = assemblyVersionMappings.SelectMany(f => f.Value)
-						.GroupBy(m => m.Key)
-						.ToDictionary(g => g.Key, g => g.Max(m => m.Value));
-
-			foreach (var framework in frameworks)
+			if (importContent)
 			{
-				foreach (var assembly in assemblyVersionMappings[framework.Attribute("Name").ToString().Split('"')[1]])
-				{
-					if (maxVersions.ContainsKey(assembly.Key) && assembly.Value == maxVersions[assembly.Key])
-					{
-						framework.Add(new XElement("import", string.Format("{0}\\{1}", framework.Attribute("Source").ToString().Split('"')[1], assembly.Key)));
-					}
-				}
-			}
+                var maxVersions = assemblyVersionMappings.SelectMany(f => f.Value)
+					.GroupBy(m => m.Key)
+					.ToDictionary(g => g.Key, g => g.Max(m => m.Value));
+
+                foreach (var framework in frameworks)
+                {
+                    foreach (var assembly in assemblyVersionMappings[framework.Attribute("Name").ToString().Split('"')[1]])
+                    {
+                        if (maxVersions.ContainsKey(assembly.Key) && assembly.Value == maxVersions[assembly.Key])
+                        {
+                            framework.Add(new XElement("import", string.Format("{0}\\{1}", framework.Attribute("Source").ToString().Split('"')[1], assembly.Key)));
+                        }
+                    }
+                }
+            }
 
 			var doc = new XDocument(new XElement("Frameworks", frameworks));
 
@@ -90,5 +103,4 @@ public override void Run (IEnumerable<string> args)
 			Console.WriteLine ($"Framework configuration file written to {configPath}");
 		}
 	}
-}
-
+}
diff --git a/mdoc/compareXmlFiles.ps1 b/mdoc/compareXmlFiles.ps1
@@ -53,8 +53,8 @@ function Git-Push([string]$rootPath, [string] $token, [string] $commitMessage, [
 
 function Run-Mdoc([string] $mdocPath, [string] $fwPath, [string] $xmlPath)
 {
-	Write-Host "$mdocPath fx-bootstrap $fwPath"
-	& $mdocPath fx-bootstrap $fwPath
+	Write-Host "$mdocPath fx-bootstrap -fx $fwPath"
+	& $mdocPath fx-bootstrap -fx $fwPath
 
 	$dnpath = [System.IO.Path]::GetDirectoryName((get-command dotnet).Source)
 	$langs=@("VB.NET","F#","C++/CLI")

diff --git a/mdoc/mdoc.nuspec b/mdoc/mdoc.nuspec
@@ -2,7 +2,7 @@
 <package >
   <metadata>
     <id>mdoc</id>
-    <version>5.9.2</version>
+    <version>5.9.2.1</version>
     <title>mdoc</title>
     <authors>Microsoft</authors>
     <owners>Microsoft</owners>