Debian Codegraph @

external/api-doc-tools/mdoc/Mono.Documentation/Updater/MsxdocDocumentationImporter.cs

raw
1 using System;
2 using System.IO;
3 using System.Linq;
4 using System.Xml;
5
6 using Mono.Cecil;
7
8 namespace Mono.Documentation.Updater
9 {
10 class MsxdocDocumentationImporter : DocumentationImporter
11 {
12 XmlDocument slashdocs;
13
14 public MsxdocDocumentationImporter (string file)
15 {
16 try
17 {
18 char oppositeSlash = Path.DirectorySeparatorChar == '/' ? '\\' : '/';
19 if (file.Contains (oppositeSlash))
20 file = file.Replace (oppositeSlash, Path.DirectorySeparatorChar);
21
22 var xml = File.ReadAllText (file);
23
24 // Ensure Unix line endings
25 xml = xml.Replace ("\r", "");
26
27 slashdocs = new XmlDocument ();
28
29 slashdocs.LoadXml (xml);
30 }
31 catch (IOException ex)
32 {
33 Console.WriteLine ($"Importer Error: {ex.Message}");
34 }
35 }
36
37 public override void ImportDocumentation (DocsNodeInfo info)
38 {
39 //first try C# compiler docIds, next other languages
40 XmlNode elem = GetDocs(info.Member ?? info.Type, MDocUpdater.csharpSlashdocFormatter) ??
41 GetDocs(info.Member ?? info.Type, MDocUpdater.msxdocxSlashdocFormatter);
42
43 if (elem == null)
44 return;
45
46 XmlElement e = info.Node;
47
48 if (elem.SelectSingleNode("summary") != null && DocUtils.NeedsOverwrite(e["summary"]))
49 MDocUpdater.ClearElement(e, "summary");
50 if (elem.SelectSingleNode("remarks") != null && DocUtils.NeedsOverwrite(e["remarks"]))
51 MDocUpdater.ClearElement(e, "remarks");
52 if (elem.SelectSingleNode("value") != null || elem.SelectSingleNode("returns") != null)
53 {
54 if (DocUtils.NeedsOverwrite(e["value"]))
55 MDocUpdater.ClearElement(e, "value");
56 if (DocUtils.NeedsOverwrite(e["returns"]))
57 MDocUpdater.ClearElement(e, "returns");
58 }
59
60
61
62 foreach (XmlNode child in elem.ChildNodes)
63 {
64 switch (child.Name)
65 {
66 case "param":
67 case "typeparam":
68 {
69 XmlAttribute name = child.Attributes["name"];
70 if (name == null)
71 break;
72 XmlElement p2 = (XmlElement)e.SelectSingleNode (child.Name + "[@name='" + name.Value + "']");
73 if (DocUtils.NeedsOverwrite(p2))
74 {
75 p2.RemoveAttribute("overwrite");
76 p2.InnerXml = child.InnerXml;
77
78 }
79 break;
80 }
81 // Occasionally XML documentation will use <returns/> on
82 // properties, so let's try to normalize things.
83 case "value":
84 case "returns":
85 {
86 XmlElement v = e.OwnerDocument.CreateElement (info.ReturnIsReturn ? "returns" : "value");
87 XmlElement p2 = (XmlElement)e.SelectSingleNode(child.Name);
88 if (p2 == null)
89 {
90 v.InnerXml = child.InnerXml;
91 e.AppendChild(v);
92 }
93 break;
94 }
95 case "altmember":
96 case "exception":
97 case "permission":
98 {
99 XmlAttribute cref = child.Attributes["cref"] ?? child.Attributes["name"];
100 if (cref == null)
101 break;
102 XmlElement a = (XmlElement)e.SelectSingleNode (child.Name + "[@cref='" + cref.Value + "']");
103 if (a == null)
104 {
105 a = e.OwnerDocument.CreateElement (child.Name);
106 a.SetAttribute ("cref", cref.Value);
107 e.AppendChild (a);
108 }
109 if(DocUtils.NeedsOverwrite(a))
110 a.InnerXml = child.InnerXml;
111 break;
112 }
113 case "seealso":
114 {
115 XmlAttribute cref = child.Attributes["cref"];
116 if (cref == null)
117 break;
118 XmlElement a = (XmlElement)e.SelectSingleNode ("altmember[@cref='" + cref.Value + "']");
119 if (a == null)
120 {
121 a = e.OwnerDocument.CreateElement ("altmember");
122 a.SetAttribute ("cref", cref.Value);
123 e.AppendChild (a);
124 }
125 break;
126 }
127 default:
128 {
129 var targetNodes = e.ChildNodes.Cast<XmlNode> ()
130 .Where (n => n.Name == child.Name)
131 .Select (n => new
132 {
133 Xml = n.OuterXml,
134 Overwrite = n.Attributes != null ? n.Attributes["overwrite"] : null
135 });
136 string sourceXml = child.OuterXml;
137
138 if (!targetNodes.Any (n => sourceXml.Equals (n.Xml) || n.Overwrite?.Value == "false"))
139 {
140 MDocUpdater.CopyNode(child, e);
141 }
142 break;
143 }
144 }
145 }
146 }
147
148 private XmlNode GetDocs (MemberReference member, MemberFormatter formatter)
149 {
150 string slashdocsig = formatter?.GetDeclaration (member);
151 if (slashdocsig != null && slashdocs != null)
152 return slashdocs.SelectSingleNode ("doc/members/member[@name='" + slashdocsig + "']");
153 return null;
154 }
155 }
156 }