| blob | 8b5b5ab08e4d440f58d3dd88d1b732cbd5ccc449 |
1 // Updater program for syncing Mono's ECMA-style documentation files
2 // with an assembly.
3 // By Joshua Tauberer <tauberer@for.net>
30 {"int", "nint"},
31 {"Int32", "nint"},
32 {"System.Int32", "System.nint"},
33 {"uint", "nuint"},
34 {"UInt32", "nuint"},
35 {"System.UInt32", "System.nuint"},
36 {"float", "nfloat"},
37 {"Single", "nfloat"},
38 {"System.Single", "System.nfloat"},
39 {"SizeF", "CoreGraphics.CGSize"},
40 {"System.Drawing.SizeF", "CoreGraphics.CGSize"},
41 {"PointF", "CoreGraphics.CGPoint"},
42 {"System.Drawing.PointF", "CoreGraphics.CGPoint"},
43 {"RectangleF", "CoreGraphics.CGRect" },
44 {"System.Drawing.RectangleF", "CoreGraphics.CGRect"}
45 };
49 {"nint", "int"},
50 {"System.nint", "System.Int32"},
51 {"nuint", "uint"},
52 {"System.nuint", "System.UInt32"},
53 {"nfloat", "float"},
54 {"System.nfloat", "System.Single"},
55 {"CoreGraphics.CGSize", "System.Drawing.SizeF"},
56 {"CoreGraphics.CGPoint", "System.Drawing.PointF"},
57 {"CoreGraphics.CGRect", "System.Drawing.RectangleF"},
58 {"MonoTouch.CoreGraphics.CGSize", "System.Drawing.SizeF"},
59 {"MonoTouch.CoreGraphics.CGPoint", "System.Drawing.PointF"},
60 {"MonoTouch.CoreGraphics.CGRect", "System.Drawing.RectangleF"}
61 };
74 }
77 }
79 }
81 }
92 }
95 }
97 }
98 // it wasn't one of the native types ... just return it
100 }
103 {
108 }
112 }
114 // TODO: Need to recursively process generic parameters
115 }
117 }
126 }
128 }
129 }
131 {
148 DocumentationEnumerator docEnum;
158 };
163 };
174 {
176 }
179 {
181 }
184 {
186 }
189 {
190 return !string.IsNullOrWhiteSpace (droppedNamespace) && droppedAssemblies.Any(da => da == forModule.Name);
191 }
194 {
196 }
198 /// <summary>Logic flag to signify that we should list assemblies at the method level, since there are multiple
199 /// assemblies for a given type/method.</summary>
203 }
204 }
208 public string PreserveTag { get; set; }
209 public static MDocUpdater Instance { get; private set; }
210 public static bool SwitchingToMagicTypes { get; private set; }
213 {
234 v => {
244 }
245 } },
277 v => {
284 } },
292 "Denotes the apistyle. Currently, only `classic` and `unified` are supported. `classic` set of assemblies should be run first, immediately followed by 'unified' assemblies with the `dropns` parameter.",
294 };
303 // validation for the api-style parameter
308 Error ("api-style 'unified' must also supply the 'dropns' parameter with at least one assembly and dropped namespace.");
318 // PARSE BASIC OPTIONS AND LOAD THE ASSEMBLY TO DOCUMENT
325 // Store types that have been forwarded to avoid duplicate generation
330 // PERFORM THE UPDATES
335 }
336 #if false
340 #endif
341 else
345 }
349 }
351 {
358 }
361 }
366 }
367 else
369 }
374 }
375 }
378 {
380 foreach (var type in asm.MainModule.ExportedTypes.Where (t => t.IsForwarder).Select (t => t.FullName))
382 }
385 {
396 }
397 }
399 }
402 {
404 }
407 {
410 assembly = AssemblyDefinition.ReadAssembly (name, new ReaderParameters { AssemblyResolver = assemblyResolver });
417 }
427 }
430 {
434 };
437 }
440 {
443 }
444 }
448 };
451 {
459 }
460 }
461 }
471 }
472 }
478 }
479 }
480 }
483 {
507 }
530 }
533 {
550 }
551 }
561 throw new InvalidOperationException("Type(s) not found: " + string.Join (", ", notFound.ToArray ()));
562 }
566 MDocUpdater app;
569 XmlDocument index;
570 XmlElement index_types;
571 XmlElement index_assemblies;
574 {
581 }
584 {
589 }
592 {
594 }
597 {
601 }
602 }
605 {
610 }
612 /// <summary>Constructs the presumed path to the type's documentation file</summary>
613 /// <returns><c>true</c>, if the type file was found, <c>false</c> otherwise.</returns>
614 /// <param name="result">A typle that contains 1) the 'reltypefile', 2) the 'typefile', and 3) the file info</param>
615 bool TryFindTypeFile(string nsname, string typename, string basepath, out Tuple<string, string, FileInfo> result) {
623 }
626 {
628 Warning ("warning: The type `{0}' is in the root namespace. This may cause problems with display within monodoc.",
633 // Must get the A+B form of the type name.
637 // Find the file, if it exists
639 nsname
640 };
643 // If dropping namespace, types may have moved into a couple of different places.
647 MDocUpdater.droppedNamespace
648 });
651 }
666 }
667 }
670 // we were not able to find a file, let's use the original type informatio.
671 // so that we create the stub in the right place.
678 }
687 }
690 // Update
696 }
700 // Stub
704 }
706 }
709 {
720 }
726 // --
733 }
734 }
735 //--
736 }
740 }
742 // Stub types not in the directory
749 }
750 }
753 {
755 }
758 {
776 }
786 }
787 }
789 }
792 {
795 index_assembly = (XmlElement)parent.SelectSingleNode ("Assembly[@Name='"+ assembly.Name.Name +"']");
813 }
819 }
823 }
826 {
829 // Add namespace and type nodes into the index file as needed
831 XmlElement nsnode = (XmlElement) index_types.SelectSingleNode ("Namespace[@Name='" + ns + "']");
836 }
843 }
846 else
850 }
853 {
855 XmlDocument index;
860 // Format change
865 }
883 }
893 }
897 private void DoUpdateAssembly (AssemblyDefinition assembly, XmlElement index_types, string source, string dest, HashSet<string> goodfiles)
898 {
901 if (!IsPublic (type) || typename.IndexOfAny (InvalidFilenameChars) >= 0 || forwardedTypes.Contains (type.FullName))
908 // Add namespace and type nodes into the index file as needed
911 // Ensure the namespace index file exists
915 }
920 }
925 }
928 }
929 }
932 {
939 }
941 private static void SortXmlNodes (XmlNode parent, XmlNodeList children, XmlNodeComparer comparer)
942 {
949 }
950 }
953 {
957 {
959 }
960 }
967 {
968 }
971 {
973 }
976 {
978 }
979 }
983 {
984 // Some of the existing docs use e.g. 1.0.x.x, which Version doesn't like.
988 }
991 {
996 }
997 }
1000 {
1012 }
1015 {
1021 }
1023 }
1025 }
1028 {
1029 // Look for files that no longer correspond to types
1030 foreach (System.IO.DirectoryInfo nsdir in new System.IO.DirectoryInfo(dest).GetDirectories("*")) {
1041 }
1045 Action saveDoc = () => {
1048 };
1050 if (e != null && !no_assembly_versions && assembly != null && assemblyName != null && UpdateAssemblyVersions (e, assembly, GetAssemblyVersions(assemblyName), false)) {
1054 }
1056 Action actuallyDelete = () => {
1058 try { System.IO.File.Delete (newname); } catch (Exception) { Warning ("Unable to delete existing file: {0}", newname); }
1059 try { typefile.MoveTo (newname); } catch (Exception) { Warning ("Unable to rename to: {0}", newname); }
1060 Console.WriteLine ("Class no longer present; file renamed: " + Path.Combine (nsdir.Name, typefile.Name));
1061 };
1067 var classicAssemblyNode = doc.SelectSingleNode ("/Type/AssemblyInfo[not(@apistyle) or @apistyle='classic']");
1068 var unifiedMembers = doc.SelectNodes ("//Member[@apistyle='unified']|//Member/AssemblyInfo[@apistyle='unified']");
1069 var classicMembers = doc.SelectNodes ("//Member[@apistyle='classic']|//Member/AssemblyInfo[@apistyle='classic']");
1074 var styledNodes = doc.SelectNodes("//*[@apistyle='"+ style.ToString ().ToLowerInvariant () +"']");
1078 }
1079 }
1081 };
1084 Warning ("*** this type is marked as unified, not deleting during this run: {0}", typefile.FullName);
1085 // if truly removed from both assemblies, it will be removed fully during the unified run
1089 // we should be safe to delete here because it was not marked as a unified assembly
1091 }
1092 }
1098 // safe to delete because it wasn't marked as a classic assembly, so the type is gone in both.
1100 }
1101 }
1102 }
1103 }
1104 }
1105 }
1106 }
1109 {
1113 );
1116 }
1119 {
1123 }
1126 {
1127 // Look for type nodes that no longer correspond to types
1130 string fulltypename = Path.Combine (((XmlElement)typenode.ParentNode).GetAttribute("Name"), typenode.GetAttribute("Name") + ".xml");
1133 }
1134 }
1137 }
1140 {
1147 }
1151 }
1152 else
1157 }
1158 }
1162 {
1175 }
1176 }
1178 static readonly XmlNodeComparer DefaultExtensionMethodComparer = new ExtensionMethodComparer ();
1180 public void DoUpdateType2 (string message, XmlDocument basefile, TypeDefinition type, string output, bool insertSince)
1181 {
1186 // Update type metadata
1189 // Update existing members. Delete member nodes that no longer should be there,
1190 // and remember what members are already documented so we don't add them again.
1199 // Check for an error condition where the xml MemberName doesn't match the matched member
1202 if (memberAttribute == null || (memberAttribute.Value != memberName && memberAttribute.Value.Split (',').Length != memberName.Split (',').Length)) {
1204 }
1205 }
1209 // Interface implementations and overrides are deleted from the docs
1210 // unless the overrides option is given.
1214 // Deleted (or signature changed)
1216 if (!no_assembly_versions && UpdateAssemblyVersions (oldmember, type.Module.Assembly, new string[]{ GetAssemblyVersion (type.Module.Assembly) }, false))
1221 }
1223 // Duplicated
1226 // ignore, already seen
1227 }
1230 else
1231 Warning ("TODO: found a duplicate member '{0}', but it's not identical to the prior member found!", sig);
1233 }
1235 // Update signature information
1238 // get all apistyles of sig from info.Node
1240 .Where (x => x.GetAttribute ("Language") == "C#" && !seenmembers.ContainsKey(x.GetAttribute("Value")))
1245 }
1246 }
1260 // Verify that the member isn't an explicitly implemented
1261 // member of an internal interface, in which case we shouldn't return true.
1268 }
1271 TypeReference iface;
1272 MethodReference imethod;
1277 }
1278 }
1281 })
1288 // this is a unified style API that obviously doesn't exist in the classic API. Let's mark
1289 // it with apistyle="unified", so that it's not displayed for classic style APIs
1291 }
1296 additions++;
1297 }
1298 }
1300 // Import code snippets from files
1309 }
1310 }
1315 }
1333 }
1336 }
1337 }
1340 {
1343 // Grab the specified region
1355 }
1358 }
1363 }
1365 }
1370 }
1371 }
1377 }
1379 }
1381 void DeleteMember (string reason, string output, XmlNode member, MyXmlNodeList todelete, TypeDefinition type)
1382 {
1385 : "{0}: XPath='/Type[@FullName=\"{2}\"]/Members/Member[@MemberName=\"{3}\"]'; Signature='{4}'";
1388 reason,
1389 output,
1392 signature);
1394 // Identify all of the different states that could affect our decision to delete the member
1401 var classicAssemblyInfo = member.SelectSingleNode ("AssemblyInfo[not(@apistyle) or @apistyle='classic']");
1406 Action actuallyDelete = () => {
1408 deletions++;
1409 };
1412 // explicitly not deleting
1418 // this is a unified run, and the member doesn't exist, but is marked as being in the classic assembly.
1423 // unified run, and the node is not classic, which means it doesn't exist anywhere.
1426 if (!isClassicRun || (isClassicRun && !nodeIsClassic && !nodeIsUnified)) { // regular codepath (ie. not classic/unified)
1429 Warning ("Removing classic from '{0}' ... will be removed in the unified run if not present there.", signature);
1433 }
1434 }
1435 }
1436 }
1440 {
1445 // generic methods *end* with '>'
1446 // it's possible for explicitly implemented generic interfaces to
1447 // contain <...> without being a generic method
1460 // if @MemberName matches, then it's either two different types of
1461 // members sharing the same name, e.g. field & property, or it's an
1462 // overloaded method.
1463 // for different type, sort based on MemberType value.
1469 // same type -- must be an overloaded method. Sort based on type
1470 // parameter count, then parameter count, then by the parameter
1471 // type names.
1481 }
1492 }
1493 // all parameters match, but return value might not match if it was
1494 // changed between one version and another.
1501 }
1504 }
1505 }
1510 {
1514 }
1517 {
1524 }
1526 // UPDATE HELPER FUNCTIONS
1528 // CREATE A STUB DOCUMENTATION FILE
1531 {
1542 }
1545 {
1549 }
1551 // STUBBING/UPDATING FUNCTIONS
1554 {
1566 () => {
1567 var node = WriteElementAttribute (root, element, "Language", f.Language, forceNewElement: true);
1570 },
1571 type);
1572 }
1576 string assemblyInfoNodeFilter = MDocUpdater.HasDroppedNamespace (type) ? "[@apistyle='unified']" : "[not(@apistyle) or @apistyle='classic']";
1577 Func<XmlElement, bool> assemblyFilter = x => x.SelectSingleNode ("AssemblyName").InnerText == type.Module.Assembly.Name.Name;
1578 foreach(var ass in root.SelectNodes ("AssemblyInfo" + assemblyInfoNodeFilter).Cast<XmlElement> ().Where (assemblyFilter))
1579 {
1583 }
1588 }
1591 else
1595 // Why-oh-why do we put assembly attributes in each type file?
1596 // Neither monodoc nor monodocs2html use them, so I'm deleting them
1597 // since they're outdated in current docs, and a waste of space.
1598 //MakeAttributes(ass, type.Assembly, true);
1604 }
1607 MakeTypeParameters (root, type.GenericParameters, type, MDocUpdater.HasDroppedNamespace(type));
1610 }
1619 // Document how this type instantiates the generic parameters of its base type
1627 throw new InvalidOperationException ("internal error: number of generic arguments doesn't match number of generic parameters.");
1637 }
1638 }
1641 }
1656 }
1659 }
1664 MakeTypeParameters (root, type.GenericParameters, type, MDocUpdater.HasDroppedNamespace(type));
1668 }
1678 }
1680 /// <summary>Adds an AssemblyInfo with AssemblyName node to an XmlElement.</summary>
1681 /// <returns>The assembly that was either added, or was already present</returns>
1683 {
1685 }
1687 /// <summary>Adds an AssemblyInfo with AssemblyName node to an XmlElement.</summary>
1688 /// <returns>The assembly that was either added, or was already present</returns>
1690 {
1696 if ((HasDroppedNamespace (module) && !string.IsNullOrWhiteSpace (currentApiStyle) && currentApiStyle != "unified") ||
1697 (isClassicRun && (string.IsNullOrWhiteSpace (currentApiStyle) || currentApiStyle != "classic"))) {
1699 }
1700 return apiStyleMatches && (existingName == null || (existingName != null && existingName.InnerText == module.Assembly.Name.Name));
1701 };
1706 () => {
1715 }
1732 };
1735 {
1737 }
1740 {
1744 }
1747 {
1760 () => {
1764 },
1765 mi);
1767 }
1777 UpdateAssemblyVersionForAssemblyInfo (node, me, new[] { GetAssemblyVersion (mi.Module.Assembly) }, add: true);
1778 }
1779 }
1782 }
1791 }
1802 }
1804 static void AddXmlNode (XmlElement[] relevant, Func<XmlElement, bool> valueMatches, Action<XmlElement> setValue, Func<XmlElement> makeNewNode, MemberReference member) {
1806 }
1808 static void AddXmlNode (XmlElement[] relevant, Func<XmlElement, bool> valueMatches, Action<XmlElement> setValue, Func<XmlElement> makeNewNode, TypeDefinition type) {
1810 }
1812 static XmlElement AddAssemblyXmlNode (XmlElement[] relevant, Func<XmlElement, bool> valueMatches, Action<XmlElement> setValue, Func<XmlElement> makeNewNode, ModuleDefinition module)
1813 {
1818 }
1824 foreach (var otherNodes in relevant.Where (n => n != thisAssemblyNode && n.DoesNotHaveApiStyle (ApiStyle.Unified))) {
1826 }
1827 }
1829 }
1831 /// <summary>Adds an xml node, reusing the node if it's available</summary>
1832 /// <param name="relevant">The existing set of nodes</param>
1833 /// <param name="valueMatches">Checks to see if the node's value matches what you're trying to write.</param>
1834 /// <param name="setValue">Sets the node's value</param>
1835 /// <param name="makeNewNode">Creates a new node, if valueMatches returns false.</param>
1836 static void AddXmlNode (XmlElement[] relevant, Func<XmlElement, bool> valueMatches, Action<XmlElement> setValue, Func<XmlElement> makeNewNode, ModuleDefinition module)
1837 {
1849 }
1853 }
1854 }
1855 }
1861 }
1862 }
1869 }
1870 }
1871 }
1872 }
1887 };
1890 {
1892 }
1895 {
1902 }
1903 }
1904 }
1912 }
1913 }
1916 {
1929 }
1937 }
1940 }
1943 {
1962 }
1968 select new { Type=namedArg.Argument.Type, Name=namedArg.Name, Value=namedArg.Argument.Value }))
1980 }
1981 }
1990 };
1996 };
1999 {
2021 if (!IsMultiAssembly || (IsMultiAssembly && sig != null && !extensionMethods.Any (ex => ex.SelectSingleNode ("Member/MemberSignature[@Language='C#']/@Value").Value == sig.Value))) {
2023 }
2024 }
2027 {
2036 }
2037 }
2041 }
2044 {
2050 }
2056 else
2060 }
2061 }
2064 {
2080 }
2083 }
2085 }
2087 // XML HELPER FUNCTIONS
2089 internal static XmlElement WriteElement(XmlNode parent, string element, bool forceNewElement = false) {
2104 }
2105 }
2106 }
2108 }
2109 private static XmlElement WriteElementText(XmlNode parent, string element, string value, bool forceNewElement = false) {
2113 }
2116 {
2121 }
2123 static XmlElement AppendElementAttributeText (XmlNode parent, string element, string attribute, string value)
2124 {
2129 }
2132 {
2136 }
2144 }
2145 private static XmlElement WriteElementAttribute(XmlElement parent, string element, string attribute, string value, bool forceNewElement = false) {
2148 }
2149 private static XmlElement WriteElementAttribute(XmlElement parent, XmlElement node, string attribute, string value) {
2152 }
2154 }
2159 }
2161 // DOCUMENTATION HELPER FUNCTIONS
2164 {
2179 }
2186 }
2193 // If it has a returns node instead of a value node, change its name.
2202 }
2206 }
2214 }
2221 }
2225 };
2228 {
2230 }
2234 {
2238 // Some documentation had param nodes with leading spaces.
2241 }
2243 // If a member has only one parameter, we can track changes to
2244 // the name of the parameter easily.
2247 }
2251 // Pick out existing and still-valid param nodes, and
2252 // create nodes for parameters not in the file.
2266 }
2268 // Remove parameters that no longer exist and check all params are in the right order.
2277 // delegate type
2280 name);
2281 }
2283 Warning ("\tXPath=/Type[@FullName=\"{0}\"]//Member[@MemberName=\"{1}\"]/Docs/param[@name=\"{2}\"]",
2286 name);
2287 }
2291 }
2293 }
2298 idx++;
2299 }
2303 }
2305 // Re-insert the parameter nodes at the top of the doc section.
2310 // Clear all existing param nodes
2313 Console.WriteLine("The following param node can only be deleted if the --delete option is given:");
2317 }
2318 }
2319 }
2320 }
2323 {
2331 }
2336 {
2337 }
2340 {
2350 }
2353 {
2358 }
2359 }
2362 {
2377 }
2380 }
2383 // Remove all text and whitespace nodes from the element so it
2384 // is outputted with nice indentation and no blank lines.
2391 }
2394 {
2402 return UpdateAssemblyVersionForAssemblyInfo (root, root.ParentNode as XmlElement, versions, add: true);
2403 else
2405 }
2408 {
2410 }
2412 private bool UpdateAssemblyVersions(XmlElement root, AssemblyDefinition assembly, string[] assemblyVersions, bool add)
2413 {
2419 // AssemblyVersions is not part of the spec
2421 }
2425 string thisNodeFilter = MDocUpdater.HasDroppedNamespace (assembly) ? newNodeFilter : oldNodeFilter;
2426 string thatNodeFilter = MDocUpdater.HasDroppedNamespace (assembly) ? oldNodeFilter : newNodeFilter;
2434 }
2437 }
2441 // there's a classic node, we should add apistyles
2444 }
2447 }
2449 static bool UpdateAssemblyVersionForAssemblyInfo (XmlElement e, XmlElement root, string[] assemblyVersions, bool add)
2450 {
2451 List<XmlNode> matches = e.SelectNodes ("AssemblyVersion").Cast<XmlNode> ().Where (v => Array.IndexOf (assemblyVersions, v.InnerText) >= 0).ToList ();
2452 // matches.Count > 0 && add: ignore -- already present
2456 }
2462 }
2463 }
2465 // matches.Count == 0 && !add: ignore -- already not present
2472 }
2474 }
2476 // FIXME: get TypeReferences instead of string comparison?
2478 // Security related attributes
2481 // Present in @RefType
2483 // For naming the indexer to use when not using indexers
2485 // for decimal constants
2487 // compiler generated code
2489 // more compiler generated code, e.g. iterator methods
2493 // extension methods
2495 // Used to differentiate 'object' from C#4 'dynamic'
2497 };
2499 private void MakeAttributes (XmlElement root, IEnumerable<string> attributes, TypeReference t=null)
2500 {
2504 }
2517 }
2523 }
2526 {
2532 };
2539 }
2540 }
2542 // this should never occur because the DefaultAttributeValueFormatter will always
2543 // successfully format the value ... but this is needed to satisfy the compiler :)
2544 throw new InvalidDataException (string.Format ("Unable to format attribute value ({0})", v.ToString ()));
2545 }
2548 {
2555 }
2557 }
2560 {
2564 }
2566 private void MakeParameters (XmlElement root, MemberReference member, IList<ParameterDefinition> parameters, bool shouldDuplicateWithNew=false)
2567 {
2572 XmlElement pe;
2574 // param info
2580 }
2582 // now find the existing node, if it's there so we can reuse it.
2588 // wasn't found, let's make sure it wasn't just cause the param name was changed
2592 .Where (x => x.GetAttribute ("Name") != p.Name && (x.GetAttribute ("Type") == ptype || x.GetAttribute ("Type") == newPType))
2595 }
2600 () => {
2609 else
2611 }
2615 },
2616 member);
2618 i++;
2619 }
2620 }
2622 private void MakeTypeParameters (XmlElement root, IList<GenericParameter> typeParams, MemberReference member, bool shouldDuplicateWithNew)
2623 {
2629 }
2641 nodes,
2642 x => {
2644 // TODO: should this comparison take into account BaseTypeName?
2646 },
2648 () => {
2659 }
2664 }
2681 }
2684 },
2685 member);
2686 }
2687 }
2690 {
2700 }
2701 }
2706 else
2708 }
2712 }
2715 {
2717 }
2719 private void MakeReturnValue (XmlElement root, TypeReference type, IList<CustomAttribute> attributes, bool shouldDuplicateWithNew=false)
2720 {
2727 () => {
2733 },
2734 type);
2735 }
2737 private void MakeReturnValue (XmlElement root, MemberReference mi, bool shouldDuplicateWithNew=false)
2738 {
2742 MakeReturnValue (root, ((MethodDefinition)mi).ReturnType, ((MethodDefinition)mi).MethodReturnType.CustomAttributes, shouldDuplicateWithNew);
2749 else
2751 }
2754 {
2761 // no documentation for property/event accessors. Is there a better way of doing this?
2780 }
2783 }
2786 {
2793 }
2798 TypeReference iface;
2799 MethodReference ifaceMethod;
2804 }
2813 }
2814 }
2816 }
2818 /// SIGNATURE GENERATION FUNCTIONS
2820 {
2822 }
2825 {
2837 }
2840 {
2842 }
2845 {
2847 }
2850 {
2862 }
2864 }
2866 }
2869 {
2887 }
2889 }
2891 }
2894 {
2908 }
2916 }
2918 }
2920 }
2921 }
2925 {
2931 }
2934 {
2947 }
2949 public static IEnumerable<MemberReference> GetMembers (this TypeDefinition type, string member)
2950 {
2952 }
2955 {
2957 }
2960 {
2964 }
2967 {
2971 }
2974 {
2986 }
2989 {
2991 }
2994 {
2998 }
3001 {
3003 }
3006 {
3008 }
3011 {
3015 }
3018 {
3020 }
3023 {
3031 }
3032 }
3035 Classic,
3036 Unified
3037 }
3045 }
3049 }
3051 {
3054 }
3060 }
3062 // Propagate the API style up to the membernode if necessary
3063 if (element.LocalName == "AssemblyInfo" && element.ParentNode != null && element.ParentNode.LocalName == "Member") {
3066 var classicAssemblyNode = member.SelectSingleNode ("AssemblyInfo[not(@apistyle) or @apistyle='classic']");
3070 Action propagateStyle = () => {
3072 // if it doesn't have the attribute, then add it
3076 }
3077 };
3079 if ((style == ApiStyle.Classic && unifiedAssemblyNode != null) || (style == ApiStyle.Unified && classicAssemblyNode != null))
3081 else
3083 }
3084 }
3086 {
3092 }
3094 }
3096 {
3101 }
3102 }
3104 {
3108 }
3109 }
3112 {
3114 }
3117 {
3124 }
3125 }
3127 }
3130 {
3135 }
3139 {
3143 throw new InvalidOperationException ("Could not determine interface type for explicitly-implemented interface member " + method.Name);
3146 }
3149 {
3150 // Issue: (g)mcs-generated assemblies that explicitly implement
3151 // properties don't specify the full namespace, just the
3152 // TypeName.Property; .NET uses Full.Namespace.TypeName.Property.
3159 // Need to determine appropriate namespace for this member.
3160 TypeReference iface;
3161 MethodReference ifaceMethod;
3166 }
3169 {
3179 // first, make sure this isn't a type reference to another assembly/module
3184 }
3186 }
3189 {
3195 }
3198 {
3199 return
3200 method.CustomAttributes
3204 }
3207 {
3213 }
3216 {
3222 }
3225 }
3228 {
3233 }
3236 {
3244 }
3246 }
3249 {
3251 }
3254 {
3262 }
3263 };
3270 }
3271 else
3273 }
3277 }
3278 }
3282 {
3284 }
3288 {
3290 }
3294 {
3296 }
3299 {
3312 }
3317 }
3318 }
3321 {
3333 }
3334 }
3337 }
3344 }
3346 // no remarks section for enum members
3349 }
3361 {
3363 }
3364 }
3368 public virtual IEnumerable<TypeDefinition> GetDocumentationTypes (AssemblyDefinition assembly, List<string> forTypes)
3369 {
3371 }
3373 protected IEnumerable<TypeDefinition> GetDocumentationTypes (AssemblyDefinition assembly, List<string> forTypes, HashSet<string> seen)
3374 {
3383 }
3384 }
3386 public virtual IEnumerable<DocsNodeInfo> GetDocumentationMembers (XmlDocument basefile, TypeDefinition type)
3387 {
3392 }
3396 }
3399 }
3400 }
3401 }
3404 {
3413 // If we're using 'magic types', then we might get false positives ... in those cases, we keep searching
3416 // Loop through all members in this type with the same name
3434 }
3435 }
3439 // check type parameters
3445 // check member parameters
3453 // Casting operators can overload based on return type.
3461 }
3463 (MDocUpdater.SwitchingToMagicTypes && returntype != originalRType && returntype != rtype && originalRType != rtype)) {
3465 }
3469 }
3479 // if magictypes, replace paramType to "classic value" ... so the comparison works
3483 }
3487 (MDocUpdater.SwitchingToMagicTypes && !originalParamType.Equals(xmlMemberType) && !paramType.Equals(xmlMemberType) && !paramType.Equals(originalParamType))) {
3489 // did not match ... if we're dropping the namespace, and the paramType has the dropped
3490 // namespace, we should see if it matches when added
3492 if (MDocUpdater.HasDroppedNamespace(type) && paramType.StartsWith (MDocUpdater.droppedNamespace)) {
3496 }
3501 }
3502 }
3506 }
3510 // we matched this on a magic type conversion ... let's keep going to see if there's another one we should look at that matches more closely
3513 }
3516 }
3519 }
3522 {
3532 }
3540 if (knownParameters != null && knownParameters.Any () && arrayTypes.Length != knownParameters.Count ())
3542 else
3544 }
3546 protected static IEnumerable<MemberReference> GetReflectionMembers (TypeDefinition type, string docName)
3547 {
3548 // In case of dropping the namespace, we have to remove the dropped NS
3549 // so that docName will match what's in the assembly/type
3550 if (MDocUpdater.HasDroppedNamespace (type) && docName.StartsWith(MDocUpdater.droppedNamespace + ".")) {
3553 }
3555 // need to worry about 4 forms of //@MemberName values:
3556 // 1. "Normal" (non-generic) member names: GetEnumerator
3557 // - Lookup as-is.
3558 // 2. Explicitly-implemented interface member names: System.Collections.IEnumerable.Current
3559 // - try as-is, and try type.member (due to "kludge" for property
3560 // support.
3561 // 3. "Normal" Generic member names: Sort<T> (CSC)
3562 // - need to remove generic parameters --> "Sort"
3563 // 4. Explicitly-implemented interface members for generic interfaces:
3564 // -- System.Collections.Generic.IEnumerable<T>.Current
3565 // - Try as-is, and try type.member, *keeping* the generic parameters.
3566 // --> System.Collections.Generic.IEnumerable<T>.Current, IEnumerable<T>.Current
3567 // 5. As of 2008-01-02, gmcs will do e.g. 'IFoo`1[A].Method' instead of
3568 // 'IFoo<A>.Method' for explicitly implemented methods; don't interpret
3569 // this as (1) or (2).
3571 // Cases 1 & 2
3575 // might be a property; try only type.member instead of
3576 // namespace.type.member.
3581 }
3582 // cases 3 & 4
3592 }
3598 // there's another character in docName, so this <...> sequence is
3599 // probably part of a generic type -- case 4.
3607 }
3608 }
3610 // case 3
3614 // case 4
3618 // If we _still_ haven't found it, we've hit another generic naming issue:
3619 // post Mono 1.1.18, gmcs generates [[FQTN]] instead of <TypeName> for
3620 // explicitly-implemented METHOD names (not properties), e.g.
3621 // "System.Collections.Generic.IEnumerable`1[[Foo, test, Version=0.0.0.0, Culture=neutral, PublicKeyToken=null]].GetEnumerator"
3622 // instead of "System.Collections.Generic.IEnumerable<Foo>.GetEnumerator",
3623 // which the XML docs will contain.
3624 //
3625 // Alas, we can't derive the Mono name from docName, so we need to iterate
3626 // over all member names, convert them into CSC format, and compare... :-(
3632 }
3633 }
3636 {
3642 }
3645 {
3650 }
3652 }
3653 }
3657 XmlReader ecmadocs;
3658 MDocUpdater app;
3661 {
3664 }
3666 public override IEnumerable<TypeDefinition> GetDocumentationTypes (AssemblyDefinition assembly, List<string> forTypes)
3667 {
3671 }
3673 new IEnumerable<TypeDefinition> GetDocumentationTypes (AssemblyDefinition assembly, List<string> forTypes, HashSet<string> seen)
3674 {
3692 TypeDefinition t;
3705 }
3706 }
3711 }
3714 }
3715 }
3716 }
3718 public override IEnumerable<DocsNodeInfo> GetDocumentationMembers (XmlDocument basefile, TypeDefinition type)
3719 {
3722 }
3725 {
3727 // do nothing
3728 }
3743 MemberReference m;
3749 // SelectSingleNode (ecmaDocsMember, "MemberSignature[@Language=\"C#\"]/@Value").Value);
3751 }
3752 // oldmember lookup may have failed due to type parameter renames.
3753 // Try again.
3765 }
3767 Console.WriteLine ("Member Added: {0}", oldmember.SelectSingleNode("MemberSignature[@Language='C#']/@Value").InnerText);
3769 }
3770 }
3777 }
3779 }
3785 }
3789 }
3791 }
3792 }
3793 }
3794 }
3799 }
3803 XmlDocument slashdocs;
3806 {
3809 // Ensure Unix line endings
3814 }
3817 {
3832 }
3845 }
3846 // Occasionally XML documentation will use <returns/> on
3847 // properties, so let's try to normalize things.
3854 }
3866 }
3869 }
3879 }
3881 }
3890 }
3891 }
3892 }
3893 }
3896 {
3901 }
3902 }
3906 XmlReader ecmadocs;
3909 {
3911 }
3914 {
3917 }
3927 else
3929 }
3944 }
3963 }
3965 }
3975 }
3978 }
3983 }
3990 }
3992 }
3994 }
3995 }
3996 }
3997 }
3998 }
4009 {
4022 shouldUse = string.IsNullOrWhiteSpace(apistyle) || apistyle == "classic"; // only use this tag if it's an 'classic' style node
4023 }
4029 }
4050 }
4054 }
4059 }
4060 }
4063 {
4072 }
4074 XmlNode rt = node.SelectSingleNode ("ReturnValue/ReturnType[not(@apistyle) or @apistyle='classic']");
4077 XmlNodeList p = node.SelectNodes ("Parameters/Parameter[not(@apistyle) or @apistyle='classic']");
4082 }
4083 XmlNodeList tp = node.SelectNodes ("TypeParameters/TypeParameter[not(@apistyle) or @apistyle='classic']");
4088 }
4091 }
4092 }
4095 {
4096 // see if we can discern the param list from the name
4103 }
4104 }
4105 }
4112 {
4113 CustomAttribute da;
4116 .SingleOrDefault (ca => ca.GetDeclaringType() == "System.Runtime.CompilerServices.DynamicAttribute"))) != null) {
4122 }
4123 }
4124 }
4127 None,
4128 WithinGenericTypeParameters,
4129 }
4134 get {return "";}
4135 }
4138 {
4140 }
4143 {
4163 }
4166 {
4168 }
4171 {
4175 }
4179 }
4181 protected virtual MemberFormatterState MemberFormatterState { get; set; }
4183 protected StringBuilder _AppendTypeName (StringBuilder buf, TypeReference type, DynamicParserContext context)
4184 {
4189 }
4192 }
4195 }
4198 }
4204 }
4206 }
4209 {
4214 }
4216 protected virtual StringBuilder AppendFullTypeName (StringBuilder buf, TypeReference type, DynamicParserContext context)
4217 {
4221 }
4223 protected virtual StringBuilder AppendTypeName (StringBuilder buf, TypeReference type, DynamicParserContext context)
4224 {
4228 }
4231 {
4236 }
4239 {
4245 }
4248 get {return "@";}
4249 }
4251 protected virtual StringBuilder AppendRefTypeName (StringBuilder buf, TypeReference type, DynamicParserContext context)
4252 {
4254 return _AppendTypeName (buf, spec != null ? spec.ElementType : type.GetElementType (), context)
4256 }
4259 get {return "*";}
4260 }
4262 protected virtual StringBuilder AppendPointerTypeName (StringBuilder buf, TypeReference type, DynamicParserContext context)
4263 {
4265 return _AppendTypeName (buf, spec != null ? spec.ElementType : type.GetElementType (), context)
4267 }
4271 }
4274 get {return '.';}
4275 }
4277 protected virtual StringBuilder AppendGenericType (StringBuilder buf, TypeReference type, DynamicParserContext context)
4278 {
4289 }
4302 }
4305 }
4306 }
4308 }
4311 {
4316 else
4319 }
4321 protected virtual StringBuilder AppendGenericTypeConstraints (StringBuilder buf, TypeReference type)
4322 {
4324 }
4327 {
4329 }
4332 {
4334 }
4337 {
4339 }
4342 {
4344 }
4347 {
4349 }
4352 {
4354 }
4357 {
4378 }
4381 {
4388 }
4391 {
4393 }
4396 {
4398 ca => ca.GetDeclaringType() == "System.Diagnostics.Contracts.ContractInvariantMethodAttribute"))
4401 // Special signature for destructors.
4416 buf.Append (GetTypeName (method.ReturnType, new DynamicParserContext (method.MethodReturnType))).Append (" ");
4423 }
4426 {
4428 }
4431 {
4433 }
4436 {
4438 }
4441 {
4443 }
4445 protected virtual StringBuilder AppendGenericMethod (StringBuilder buf, MethodDefinition method)
4446 {
4448 }
4450 protected virtual StringBuilder AppendParameters (StringBuilder buf, MethodDefinition method, IList<ParameterDefinition> parameters)
4451 {
4453 }
4455 protected virtual StringBuilder AppendGenericMethodConstraints (StringBuilder buf, MethodDefinition method)
4456 {
4458 }
4461 {
4463 }
4466 {
4468 }
4471 {
4473 }
4474 }
4479 get {return "ILAsm";}
4480 }
4485 }
4486 }
4489 {
4496 else
4499 }
4501 }
4504 {
4525 }
4527 }
4530 {
4532 }
4534 protected override StringBuilder AppendTypeName (StringBuilder buf, TypeReference type, DynamicParserContext context)
4535 {
4539 }
4544 }
4546 }
4548 private StringBuilder AppendGenericParameterConstraints (StringBuilder buf, GenericParameter type)
4549 {
4552 }
4567 }
4569 }
4577 }
4580 {
4616 else
4618 }
4620 foreach (var name in type.Interfaces.Where (i => MDocUpdater.IsPublic (i.InterfaceType.Resolve ()))
4626 }
4629 }
4631 }
4634 }
4636 protected override StringBuilder AppendGenericType (StringBuilder buf, TypeReference type, DynamicParserContext context)
4637 {
4645 }
4648 }
4656 }
4659 }
4662 {
4674 }
4675 }
4678 {
4680 }
4683 {
4718 }
4742 }
4744 }
4752 _AppendTypeName (buf, method.Parameters [i].ParameterType, new DynamicParserContext (method.Parameters [i]));
4755 }
4765 }
4768 {
4770 TypeReference iface;
4771 MethodReference ifaceMethod;
4776 }
4778 }
4781 get {return "";}
4782 }
4785 {
4795 }
4798 {
4804 }
4811 }
4813 protected override StringBuilder AppendGenericMethod (StringBuilder buf, MethodDefinition method)
4814 {
4823 }
4824 }
4826 }
4828 protected override StringBuilder AppendParameters (StringBuilder buf, MethodDefinition method, IList<ParameterDefinition> parameters)
4829 {
4831 }
4833 private StringBuilder AppendParameters (StringBuilder buf, MethodDefinition method, IList<ParameterDefinition> parameters, char begin, char end)
4834 {
4844 }
4845 }
4848 }
4851 {
4855 else
4857 }
4860 }
4863 {
4896 }
4900 }
4903 {
4926 }
4929 {
4939 }
4942 {
4943 // enums have a value__ field, which we ignore
4952 }
4966 else
4971 }
4972 }
4974 }
4977 {
4981 }
4990 }
4991 }
4995 {
4997 }
4998 }
5002 {
5003 //string moddedType = base.GetBuiltinType (t);
5005 //return moddedType;
5006 }
5007 }
5025 }
5027 }
5028 }
5033 get {return "C#";}
5034 }
5037 {
5043 }
5046 {
5066 }
5068 }
5070 protected override StringBuilder AppendTypeName (StringBuilder buf, TypeReference type, DynamicParserContext context)
5071 {
5076 }
5079 return AppendGenericParameterConstraints (buf, (GenericParameter) type, context).Append (type.Name);
5083 }
5090 }
5093 }
5095 private StringBuilder AppendGenericParameterConstraints (StringBuilder buf, GenericParameter type, DynamicParserContext context)
5096 {
5107 }
5110 {
5125 buf.Append (full.GetName (invoke.ReturnType, new DynamicParserContext (invoke.MethodReturnType))).Append (" ");
5132 }
5163 }
5169 }
5171 }
5174 }
5177 {
5187 }
5190 {
5202 }
5203 }
5205 protected override StringBuilder AppendGenericTypeConstraints (StringBuilder buf, TypeReference type)
5206 {
5210 }
5213 {
5231 }
5235 }
5242 }
5247 }
5248 }
5250 }
5253 {
5265 }
5268 {
5273 }
5276 {
5278 TypeReference iface;
5279 MethodReference ifaceMethod;
5284 }
5286 }
5288 protected override StringBuilder AppendGenericMethodConstraints (StringBuilder buf, MethodDefinition method)
5289 {
5293 }
5296 get {return "";}
5297 }
5300 {
5302 }
5305 {
5313 }
5316 {
5322 }
5329 }
5331 protected override StringBuilder AppendGenericMethod (StringBuilder buf, MethodDefinition method)
5332 {
5341 }
5342 }
5344 }
5346 protected override StringBuilder AppendParameters (StringBuilder buf, MethodDefinition method, IList<ParameterDefinition> parameters)
5347 {
5349 }
5351 private StringBuilder AppendParameters (StringBuilder buf, MethodDefinition method, IList<ParameterDefinition> parameters, char begin, char end)
5352 {
5362 }
5363 }
5366 }
5369 {
5373 else
5375 }
5376 buf.Append (GetTypeName (parameter.ParameterType, new DynamicParserContext (parameter))).Append (" ");
5379 buf.AppendFormat (" = {0}", MDocUpdater.MakeAttributesValueString (parameter.Constant, parameter.ParameterType));
5380 }
5382 }
5385 {
5386 MethodDefinition method;
5404 if (get_visible != null && (set_visible == null || (set_visible != null && get_visible == set_visible)))
5408 else
5411 // Pick an accessor to use for static/virtual/override/etc. checks.
5421 else
5423 }
5433 buf.Append (GetTypeName (property.PropertyType, new DynamicParserContext (property))).Append (' ');
5441 }
5442 }
5447 }
5454 }
5459 }
5463 }
5466 {
5486 buf.Append (' ').Append (GetTypeName (field.FieldType, new DynamicParserContext (field))).Append (' ');
5492 }
5495 {
5501 }
5504 {
5505 // enums have a value__ field, which we ignore
5515 }
5525 }
5526 }
5528 }
5531 {
5535 }
5540 buf.Append (GetTypeName (e.EventType, new DynamicParserContext (e.AddMethod.Parameters [0]))).Append (' ');
5544 }
5545 }
5549 {
5551 }
5552 }
5558 get {return '+';}
5559 }
5560 }
5564 {
5566 }
5567 }
5573 }
5575 private bool AddTypeCount = true;
5577 private TypeReference genDeclType;
5578 private MethodReference genDeclMethod;
5580 protected override StringBuilder AppendTypeName (StringBuilder buf, TypeReference type, DynamicParserContext context)
5581 {
5582 if (type is GenericParameter) {
5583 int l = buf.Length;
5584 if (genDeclType != null) {
5585 IList<GenericParameter> genArgs = genDeclType.GenericParameters;
5586 for (int i = 0; i < genArgs.Count; ++i) {
5587 if (genArgs [i].Name == type.Name) {
5589 break;
5590 }
5591 }
5592 }
5593 if (genDeclMethod != null) {
5594 IList<GenericParameter> genArgs = null;
5595 if (genDeclMethod.IsGenericMethod ()) {
5596 genArgs = genDeclMethod.GenericParameters;
5597 for (int i = 0; i < genArgs.Count; ++i) {
5598 if (genArgs [i].Name == type.Name) {
5599 buf.Append ("``").Append (i);
5600 break;
5601 }
5602 }
5603 }
5604 }
5605 if (genDeclType == null && genDeclMethod == null) {
5606 // Probably from within an explicitly implemented interface member,
5607 // where CSC uses parameter names instead of indices (why?), e.g.
5610 buf.Append (type.Name);
5611 }
5612 if (buf.Length == l) {
5613 throw new Exception (string.Format (
5615 type.Name, genDeclType, genDeclMethod));
5616 }
5617 }
5618 else {
5619 base.AppendTypeName (buf, type, context);
5620 if (AddTypeCount) {
5621 int numArgs = type.GenericParameters.Count;
5622 if (type.DeclaringType != null)
5623 numArgs -= type.GenericParameters.Count;
5624 if (numArgs > 0) {
5626 }
5627 }
5628 }
5629 return buf;
5630 }
5632 protected override StringBuilder AppendArrayModifiers (StringBuilder buf, ArrayType array)
5633 {
5634 buf.Append (ArrayDelimeters [0]);
5635 int rank = array.Rank;
5636 if (rank > 1) {
5637 buf.Append ("0:");
5638 for (int i = 1; i < rank; ++i) {
5639 buf.Append (",0:");
5640 }
5641 }
5642 return buf.Append (ArrayDelimeters [1]);
5643 }
5645 protected override StringBuilder AppendGenericType (StringBuilder buf, TypeReference type, DynamicParserContext context)
5646 {
5647 if (!AddTypeCount)
5648 base.AppendGenericType (buf, type, context);
5649 else
5650 AppendType (buf, type, context);
5651 return buf;
5652 }
5654 private StringBuilder AppendType (StringBuilder buf, TypeReference type, DynamicParserContext context)
5655 {
5656 List<TypeReference> decls = DocUtils.GetDeclaringTypes (type);
5657 bool insertNested = false;
5658 int prevParamCount = 0;
5659 foreach (var decl in decls) {
5660 if (insertNested)
5661 buf.Append (NestedTypeSeparator);
5662 insertNested = true;
5663 base.AppendTypeName (buf, decl, context);
5664 int argCount = DocUtils.GetGenericArgumentCount (decl);
5665 int numArgs = argCount - prevParamCount;
5666 prevParamCount = argCount;
5667 if (numArgs > 0)
5669 }
5670 return buf;
5671 }
5673 protected override string GetConstructorName (MethodReference constructor)
5674 {
5675 return GetMethodDefinitionName (constructor, "#ctor");
5676 }
5678 protected override string GetMethodName (MethodReference method)
5679 {
5680 string name = null;
5681 MethodDefinition methodDef = method as MethodDefinition;
5682 if (methodDef == null || !DocUtils.IsExplicitlyImplemented (methodDef))
5683 name = method.Name;
5684 else {
5685 TypeReference iface;
5686 MethodReference ifaceMethod;
5687 DocUtils.GetInfoForExplicitlyImplementedMethod (methodDef, out iface, out ifaceMethod);
5688 AddTypeCount = false;
5689 name = GetTypeName (iface) + "." + ifaceMethod.Name;
5690 AddTypeCount = true;
5691 }
5692 return GetMethodDefinitionName (method, name);
5693 }
5695 private string GetMethodDefinitionName (MethodReference method, string name)
5696 {
5697 StringBuilder buf = new StringBuilder ();
5698 buf.Append (GetTypeName (method.DeclaringType));
5700 buf.Append (name.Replace (".", "#"));
5701 if (method.IsGenericMethod ()) {
5702 IList<GenericParameter> genArgs = method.GenericParameters;
5703 if (genArgs.Count > 0)
5704 buf.Append ("``").Append (genArgs.Count);
5705 }
5706 IList<ParameterDefinition> parameters = method.Parameters;
5707 try {
5708 genDeclType = method.DeclaringType;
5709 genDeclMethod = method;
5710 AppendParameters (buf, method.DeclaringType.GenericParameters, parameters);
5711 }
5712 finally {
5713 genDeclType = null;
5714 genDeclMethod = null;
5715 }
5716 return buf.ToString ();
5717 }
5719 private StringBuilder AppendParameters (StringBuilder buf, IList<GenericParameter> genArgs, IList<ParameterDefinition> parameters)
5720 {
5721 if (parameters.Count == 0)
5722 return buf;
5726 AppendParameter (buf, genArgs, parameters [0]);
5727 for (int i = 1; i < parameters.Count; ++i) {
5729 AppendParameter (buf, genArgs, parameters [i]);
5730 }
5733 }
5735 private StringBuilder AppendParameter (StringBuilder buf, IList<GenericParameter> genArgs, ParameterDefinition parameter)
5736 {
5737 AddTypeCount = false;
5738 buf.Append (GetTypeName (parameter.ParameterType));
5739 AddTypeCount = true;
5740 return buf;
5741 }
5743 protected override string GetPropertyName (PropertyReference property)
5744 {
5745 string name = null;
5747 PropertyDefinition propertyDef = property as PropertyDefinition;
5748 MethodDefinition method = null;
5749 if (propertyDef != null)
5750 method = propertyDef.GetMethod ?? propertyDef.SetMethod;
5751 if (method != null && !DocUtils.IsExplicitlyImplemented (method))
5752 name = property.Name;
5753 else {
5754 TypeReference iface;
5755 MethodReference ifaceMethod;
5756 DocUtils.GetInfoForExplicitlyImplementedMethod (method, out iface, out ifaceMethod);
5757 AddTypeCount = false;
5758 name = string.Join ("#", new string[]{
5759 GetTypeName (iface).Replace (".", "#"),
5760 DocUtils.GetMember (property.Name)
5761 });
5762 AddTypeCount = true;
5763 }
5765 StringBuilder buf = new StringBuilder ();
5766 buf.Append (GetName (property.DeclaringType));
5768 buf.Append (name);
5769 IList<ParameterDefinition> parameters = property.Parameters;
5770 if (parameters.Count > 0) {
5771 genDeclType = property.DeclaringType;
5773 IList<GenericParameter> genArgs = property.DeclaringType.GenericParameters;
5774 AppendParameter (buf, genArgs, parameters [0]);
5775 for (int i = 1; i < parameters.Count; ++i) {
5777 AppendParameter (buf, genArgs, parameters [i]);
5778 }
5780 genDeclType = null;
5781 }
5782 return buf.ToString ();
5783 }
5785 protected override string GetFieldName (FieldReference field)
5786 {
5788 GetName (field.DeclaringType), field.Name);
5789 }
5791 protected override string GetEventName (EventReference e)
5792 {
5794 GetName (e.DeclaringType), e.Name);
5795 }
5797 protected override string GetTypeDeclaration (TypeDefinition type)
5798 {
5799 string name = GetName (type);
5800 if (type == null)
5801 return null;
5802 return "T:" + name;
5803 }
5805 protected override string GetConstructorDeclaration (MethodDefinition constructor)
5806 {
5807 string name = GetName (constructor);
5808 if (name == null)
5809 return null;
5810 return "M:" + name;
5811 }
5813 protected override string GetMethodDeclaration (MethodDefinition method)
5814 {
5815 string name = GetName (method);
5816 if (name == null)
5817 return null;
5818 if (method.Name == "op_Implicit" || method.Name == "op_Explicit") {
5819 genDeclType = method.DeclaringType;
5820 genDeclMethod = method;
5821 name += "~" + GetName (method.ReturnType);
5822 genDeclType = null;
5823 genDeclMethod = null;
5824 }
5825 return "M:" + name;
5826 }
5828 protected override string GetPropertyDeclaration (PropertyDefinition property)
5829 {
5830 string name = GetName (property);
5831 if (name == null)
5832 return null;
5833 return "P:" + name;
5834 }
5836 protected override string GetFieldDeclaration (FieldDefinition field)
5837 {
5838 string name = GetName (field);
5839 if (name == null)
5840 return null;
5841 return "F:" + name;
5842 }
5844 protected override string GetEventDeclaration (EventDefinition e)
5845 {
5846 string name = GetName (e);
5847 if (name == null)
5848 return null;
5849 return "E:" + name;
5850 }
5851 }
5853 class FileNameMemberFormatter : SlashDocMemberFormatter {
5854 protected override StringBuilder AppendNamespace (StringBuilder buf, TypeReference type)
5855 {
5856 return buf;
5857 }
5859 protected override char NestedTypeSeparator {
5861 }
5862 }
5864 class ResolvedTypeInfo {
5865 TypeDefinition typeDef;
5867 public ResolvedTypeInfo (TypeReference value) {
5868 Reference = value;
5869 }
5873 public TypeDefinition Definition {
5874 get {
5875 if (typeDef == null) {
5876 typeDef = Reference.Resolve ();
5877 }
5878 return typeDef;
5879 }
5880 }
5881 }
5883 /// <summary>Formats attribute values. Should return true if it is able to format the value.</summary>
5884 class AttributeValueFormatter {
5885 public virtual bool TryFormatValue (object v, ResolvedTypeInfo type, out string returnvalue)
5886 {
5887 TypeReference valueType = type.Reference;
5888 if (v == null) {
5889 returnvalue = "null";
5890 return true;
5891 }
5892 if (valueType.FullName == "System.Type") {
5893 var vTypeRef = v as TypeReference;
5894 if (vTypeRef != null)
5895 returnvalue = "typeof(" + NativeTypeManager.GetTranslatedName (vTypeRef) + ")"; // TODO: drop NS handling
5896 else
5897 returnvalue = "typeof(" + v.ToString () + ")";
5899 return true;
5900 }
5901 if (valueType.FullName == "System.String") {
5903 return true;
5904 }
5905 if (valueType.FullName == "System.Char") {
5907 return true;
5908 }
5909 if (v is Boolean) {
5910 returnvalue = (bool)v ? "true" : "false";
5911 return true;
5912 }
5914 TypeDefinition valueDef = type.Definition;
5915 if (valueDef == null || !valueDef.IsEnum) {
5916 returnvalue = v.ToString ();
5917 return true;
5918 }
5920 string typename = MDocUpdater.GetDocTypeFullName (valueType);
5921 var values = MDocUpdater.GetEnumerationValues (valueDef);
5922 long c = MDocUpdater.ToInt64 (v);
5923 if (values.ContainsKey (c)) {
5924 returnvalue = typename + "." + values [c];
5925 return true;
5926 }
5928 returnvalue = null;
5929 return false;
5930 }
5931 }
5933 /// <summary>The final value formatter in the pipeline ... if no other formatter formats the value,
5934 /// then this one will serve as the default implementation.</summary>
5935 class DefaultAttributeValueFormatter : AttributeValueFormatter {
5936 public override bool TryFormatValue (object v, ResolvedTypeInfo type, out string returnvalue)
5937 {
5938 returnvalue = "(" + MDocUpdater.GetDocTypeFullName (type.Reference) + ") " + v.ToString ();
5939 return true;
5940 }
5941 }
5943 /// <summary>Flags enum formatter that assumes powers of two values.</summary>
5944 /// <remarks>As described here: https://msdn.microsoft.com/en-us/library/vstudio/ms229062(v=vs.100).aspx</remarks>
5945 class StandardFlagsEnumFormatter : AttributeValueFormatter {
5946 public override bool TryFormatValue (object v, ResolvedTypeInfo type, out string returnvalue)
5947 {
5948 TypeReference valueType = type.Reference;
5949 TypeDefinition valueDef = type.Definition;
5950 if (valueDef.CustomAttributes.Any (ca => ca.AttributeType.FullName == "System.FlagsAttribute")) {
5952 string typename = MDocUpdater.GetDocTypeFullName (valueType);
5953 var values = MDocUpdater.GetEnumerationValues (valueDef);
5954 long c = MDocUpdater.ToInt64 (v);
5955 returnvalue = string.Join (" | ",
5956 (from i in values.Keys
5957 where (c & i) == i && i != 0
5958 select typename + "." + values [i])
5959 .DefaultIfEmpty (c.ToString ()).ToArray ());
5961 return true;
5962 }
5964 returnvalue = null;
5965 return false;
5966 }
5967 }
5969 /// <summary>A custom formatter for the ObjCRuntime.Platform enumeration.</summary>
5970 class ApplePlatformEnumFormatter : AttributeValueFormatter {
5971 public override bool TryFormatValue (object v, ResolvedTypeInfo type, out string returnvalue)
5972 {
5973 TypeReference valueType = type.Reference;
5974 string typename = MDocUpdater.GetDocTypeFullName (valueType);
5975 TypeDefinition valueDef = type.Definition;
5976 if (typename.Contains ("ObjCRuntime.Platform") && valueDef.CustomAttributes.Any (ca => ca.AttributeType.FullName == "System.FlagsAttribute")) {
5978 var values = MDocUpdater.GetEnumerationValues (valueDef);
5979 long c = MDocUpdater.ToInt64 (v);
5981 returnvalue = Format (c, values, typename);
5982 return true;
5983 }
5985 returnvalue = null;
5986 return false;
5987 }
5989 string Format (long c, IDictionary<long, string> values, string typename)
5990 {
5991 int iosarch, iosmajor, iosminor, iossubminor;
5992 int macarch, macmajor, macminor, macsubminor;
5993 GetEncodingiOS (c, out iosarch, out iosmajor, out iosminor, out iossubminor);
5994 GetEncodingMac ((ulong)c, out macarch, out macmajor, out macminor, out macsubminor);
5996 if (iosmajor == 0 & iosminor == 0 && iossubminor == 0) {
5997 return FormatValues ("Mac", macarch, macmajor, macminor, macsubminor);
5998 }
6000 if (macmajor == 0 & macminor == 0 && macsubminor == 0) {
6001 return FormatValues ("iOS", iosarch, iosmajor, iosminor, iossubminor);
6002 }
6005 }
6007 string FormatValues (string plat, int arch, int major, int minor, int subminor)
6008 {
6009 string archstring = "";
6010 switch (arch) {
6011 case 1:
6012 archstring = "32";
6013 break;
6014 case 2:
6015 archstring = "64";
6016 break;
6017 }
6019 major,
6020 minor,
6021 subminor == 0 ? "" : "_" + subminor.ToString (),
6022 archstring,
6023 plat
6024 );
6025 }
6027 void GetEncodingiOS (long entireLong, out int archindex, out int major, out int minor, out int subminor)
6028 {
6029 long lowerBits = entireLong & 0xffffffff;
6030 int lowerBitsAsInt = (int) lowerBits;
6031 GetEncoding (lowerBitsAsInt, out archindex, out major, out minor, out subminor);
6032 }
6034 void GetEncodingMac (ulong entireLong, out int archindex, out int major, out int minor, out int subminor)
6035 {
6036 ulong higherBits = entireLong & 0xffffffff00000000;
6037 int higherBitsAsInt = (int) ((higherBits) >> 32);
6038 GetEncoding (higherBitsAsInt, out archindex, out major, out minor, out subminor);
6039 }
6041 void GetEncoding (Int32 encodedBits, out int archindex, out int major, out int minor, out int subminor)
6042 {
6043 // format is AAJJNNSS
6044 archindex = (int)((encodedBits & 0xFF000000) >> 24);
6045 major = (int)((encodedBits & 0x00FF0000) >> 16);
6046 minor = (int)((encodedBits & 0x0000FF00) >> 8);
6047 subminor = (int)((encodedBits & 0x000000FF) >> 0);
6048 }
6049 }
6050 }