Debian Codegraph @

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

raw
1 using System;
2 using System.Collections.Generic;
3 using System.Linq;
4 using System.Text;
5
6
7 using Mono.Documentation.Util;
8 using Mono.Cecil;
9
10 namespace Mono.Documentation.Updater
11 {
12 public abstract class MemberFormatter
13 {
14
15 public virtual string Language
16 {
17 get { return ""; }
18 }
19
20 public string GetName (MemberReference member, bool appendGeneric = true)
21 {
22 return GetName (member, null, appendGeneric);
23 }
24
25 public virtual string GetName (MemberReference member, DynamicParserContext context, bool appendGeneric = true)
26 {
27 TypeReference type = member as TypeReference;
28 if (type != null)
29 return GetTypeName (type, context, appendGeneric);
30 MethodReference method = member as MethodReference;
31 if (method != null && method.Name == ".ctor") // method.IsConstructor
32 return GetConstructorName (method);
33 if (method != null)
34 return GetMethodName (method);
35 PropertyReference prop = member as PropertyReference;
36 if (prop != null)
37 return GetPropertyName (prop);
38 FieldReference field = member as FieldReference;
39 if (field != null)
40 return GetFieldName (field);
41 EventReference e = member as EventReference;
42 if (e != null)
43 return GetEventName (e);
44 throw new NotSupportedException ("Can't handle: " +
45 (member == null ? "null" : member.GetType ().ToString ()));
46 }
47
48 protected virtual string GetTypeName (TypeReference type, bool appendGeneric = true)
49 {
50 return GetTypeName (type, null, appendGeneric);
51 }
52
53 protected virtual string GetTypeName (TypeReference type, DynamicParserContext context, bool appendGeneric=true)
54 {
55 if (type == null)
56 throw new ArgumentNullException (nameof (type));
57
58 var typeName = _AppendTypeName (new StringBuilder (type.Name.Length), type, context, appendGeneric).ToString ();
59
60 typeName = RemoveMod (typeName);
61
62 return typeName;
63 }
64
65 public static string RemoveMod (string typeName)
66 {
67 if (string.IsNullOrWhiteSpace (typeName)) return typeName;
68
69 // For custom modifiers (modopt/modreq), we are just excising them
70 // via string manipulation for simplicity; since these cannot be
71 // expressed in C#. If finer control is needed in the future, you can
72 // use IModifierType, PointerType, ByReferenceType, etc.
73
74 int modIndex = System.Math.Max (typeName.LastIndexOf ("modopt(", StringComparison.Ordinal), typeName.LastIndexOf ("modreq(", StringComparison.Ordinal));
75 if (modIndex > 0)
76 {
77 var tname = typeName.Substring (0, modIndex - 1);
78 var parenIndex = typeName.LastIndexOf (')');
79 if (parenIndex == typeName.Length - 2)
80 { // see if there's metadata like a pointer
81 tname += typeName.Last ();
82 }
83 typeName = tname;
84 }
85
86 modIndex = System.Math.Max (typeName.LastIndexOf ("modopt(", StringComparison.Ordinal), typeName.LastIndexOf ("modreq(", StringComparison.Ordinal));
87 if (modIndex >= 0)
88 return RemoveMod (typeName);
89 else
90 return typeName;
91 }
92
93 protected virtual char[] ArrayDelimeters
94 {
95 get { return new char[] { '[', ']' }; }
96 }
97
98 protected virtual MemberFormatterState MemberFormatterState { get; set; }
99
100 protected virtual StringBuilder AppendArrayTypeName(StringBuilder buf, TypeReference type, DynamicParserContext context)
101 {
102 TypeSpecification spec = type as TypeSpecification;
103 _AppendTypeName(buf, spec != null ? spec.ElementType : type.GetElementType(), context);
104 return AppendArrayModifiers(buf, (ArrayType)type);
105 }
106
107 protected StringBuilder _AppendTypeName (StringBuilder buf, TypeReference type, DynamicParserContext context, bool appendGeneric = true)
108 {
109 if (type == null)
110 return buf;
111
112 if (type is ArrayType)
113 {
114 return AppendArrayTypeName(buf, type, context);
115 }
116 if (type is ByReferenceType)
117 {
118 return AppendRefTypeName (buf, type, context);
119 }
120 if (type is PointerType)
121 {
122 return AppendPointerTypeName (buf, type, context);
123 }
124 if (type is GenericParameter)
125 {
126 return AppendTypeName (buf, type, context);
127 }
128 AppendNamespace (buf, type);
129 GenericInstanceType genInst = type as GenericInstanceType;
130
131 if (type.IsRequiredModifier)
132 {
133 try
134 {
135 var rtype = type.Resolve ();
136 if (rtype != null)
137 type = rtype;
138 }
139 catch (Exception)
140 {
141 // Suppress resolving error for UWP libraries.
142 // It seems, they never have `type.IsRequiredModifier == true`, but just in case.
143 }
144 }
145
146
147 if (type.GenericParameters.Count == 0 &&
148 (genInst == null ? true : genInst.GenericArguments.Count == 0))
149 {
150 return AppendFullTypeName (buf, type, context);
151 }
152 return AppendGenericType (buf, type, context, appendGeneric);
153 }
154
155 protected virtual StringBuilder AppendNamespace (StringBuilder buf, TypeReference type)
156 {
157 string ns = DocUtils.GetNamespace (type);
158 if (ns != null && ns.Length > 0)
159 buf.Append (ns).Append ('.');
160 return buf;
161 }
162
163 protected virtual StringBuilder AppendFullTypeName (StringBuilder buf, TypeReference type, DynamicParserContext context)
164 {
165 if (type.DeclaringType != null)
166 AppendFullTypeName (buf, type.DeclaringType, context).Append (NestedTypeSeparator);
167 return AppendTypeName (buf, type, context);
168 }
169
170 protected virtual StringBuilder AppendTypeName (StringBuilder buf, TypeReference type, DynamicParserContext context)
171 {
172 if (context != null)
173 context.TransformIndex++;
174 return AppendTypeName (buf, type.Name);
175 }
176
177 protected virtual StringBuilder AppendTypeName (StringBuilder buf, string typename)
178 {
179 int n = typename.IndexOf ("`");
180 if (n >= 0)
181 return buf.Append (typename.Substring (0, n));
182 return buf.Append (typename);
183 }
184
185 protected virtual StringBuilder AppendArrayModifiers (StringBuilder buf, ArrayType array)
186 {
187 buf.Append (ArrayDelimeters[0]);
188 int rank = array.Rank;
189 if (rank > 1)
190 buf.Append (new string (',', rank - 1));
191 return buf.Append (ArrayDelimeters[1]);
192 }
193
194 protected virtual string RefTypeModifier
195 {
196 get { return "@"; }
197 }
198
199 protected virtual StringBuilder AppendRefTypeName (StringBuilder buf, TypeReference type, DynamicParserContext context)
200 {
201 TypeSpecification spec = type as TypeSpecification;
202 return _AppendTypeName(buf, spec != null ? spec.ElementType : type.GetElementType(), context);
203 }
204
205 protected virtual string PointerModifier
206 {
207 get { return "*"; }
208 }
209
210 protected virtual StringBuilder AppendPointerTypeName (StringBuilder buf, TypeReference type, DynamicParserContext context)
211 {
212 TypeSpecification spec = type as TypeSpecification;
213 return _AppendTypeName (buf, spec != null ? spec.ElementType : type.GetElementType (), context)
214 .Append (PointerModifier);
215 }
216
217 protected virtual string[] GenericTypeContainer
218 {
219 get { return new string[] { "<", ">" }; }
220 }
221
222 protected virtual string NestedTypeSeparator
223 {
224 get { return "."; }
225 }
226
227 protected virtual StringBuilder AppendGenericType (StringBuilder buf, TypeReference type, DynamicParserContext context, bool appendGeneric = true)
228 {
229 List<TypeReference> decls = DocUtils.GetDeclaringTypes (
230 type is GenericInstanceType ? type.GetElementType () : type);
231 List<TypeReference> genArgs = GetGenericArguments (type);
232 int argIdx = 0;
233 int prev = 0;
234 bool insertNested = false;
235 foreach (var decl in decls)
236 {
237 TypeReference declDef = decl.Resolve () ?? decl;
238 if (insertNested)
239 {
240 buf.Append (NestedTypeSeparator);
241 }
242 insertNested = true;
243 AppendTypeName (buf, declDef, context);
244 int ac = DocUtils.GetGenericArgumentCount (declDef);
245 int c = ac - prev;
246 prev = ac;
247 if ( appendGeneric && c > 0)
248 {
249 buf.Append (GenericTypeContainer[0]);
250 var origState = MemberFormatterState;
251 MemberFormatterState = MemberFormatterState.WithinGenericTypeParameters;
252 _AppendTypeName (buf, genArgs[argIdx++], context);
253 for (int i = 1; i < c; ++i)
254 {
255 _AppendTypeName (buf.Append (","), genArgs[argIdx++], context);
256 }
257 MemberFormatterState = origState;
258 buf.Append (GenericTypeContainer[1]);
259 }
260 }
261 return buf;
262 }
263
264 protected List<TypeReference> GetGenericArguments (TypeReference type)
265 {
266 var args = new List<TypeReference> ();
267 GenericInstanceType inst = type as GenericInstanceType;
268 if (inst != null)
269 args.AddRange (inst.GenericArguments);
270 else
271 args.AddRange (type.GenericParameters);
272 return args;
273 }
274
275 protected virtual StringBuilder AppendGenericTypeConstraints (StringBuilder buf, TypeReference type)
276 {
277 return buf;
278 }
279
280 protected virtual string GetConstructorName (MethodReference constructor)
281 {
282 return constructor.Name;
283 }
284
285 protected virtual string GetMethodName (MethodReference method)
286 {
287 return method.Name;
288 }
289
290 protected virtual string GetPropertyName (PropertyReference property)
291 {
292 return property.Name;
293 }
294
295 protected virtual string GetFieldName (FieldReference field)
296 {
297 return field.Name;
298 }
299
300 protected virtual string GetEventName (EventReference e)
301 {
302 return e.Name;
303 }
304
305 public virtual string GetDeclaration (TypeReference tref)
306 {
307 if (!IsSupported(tref))
308 return null;
309 var typeSpec = tref as TypeSpecification;
310 if (typeSpec != null && typeSpec.Resolve () == null && typeSpec.IsArray && typeSpec.ContainsGenericParameter)
311 {
312 //HACK: there's really no good reference for a generic parameter array, so we're going to use object
313 return "T:System.Array";
314 }
315 TypeDefinition def = tref.Resolve ();
316 if (def != null)
317 return GetTypeDeclaration (def);
318 else
319 return GetTypeName (tref);
320 }
321
322 public virtual string GetDeclaration (MemberReference mreference)
323 {
324 if (!IsSupported(mreference))
325 return null;
326 return GetDeclaration (mreference.Resolve ());
327 }
328
329 string GetDeclaration (IMemberDefinition member)
330 {
331 if (member == null)
332 throw new ArgumentNullException ("member");
333 TypeDefinition type = member as TypeDefinition;
334 if (type != null)
335 return GetTypeDeclaration (type);
336 MethodDefinition method = member as MethodDefinition;
337 if (method != null && method.IsConstructor)
338 return GetConstructorDeclaration (method);
339 if (method != null)
340 return GetMethodDeclaration (method);
341 PropertyDefinition prop = member as PropertyDefinition;
342 if (prop != null)
343 return GetPropertyDeclaration (prop);
344 FieldDefinition field = member as FieldDefinition;
345 if (field != null)
346 return GetFieldDeclaration (field);
347 EventDefinition e = member as EventDefinition;
348 if (e != null)
349 return GetEventDeclaration (e);
350 AttachedEventDefinition ae = member as AttachedEventDefinition;
351 if (ae != null)
352 return GetAttachedEventDeclaration (ae);
353 AttachedPropertyDefinition ap = member as AttachedPropertyDefinition;
354 if (ap != null)
355 return GetAttachedPropertyDeclaration (ap);
356 throw new NotSupportedException ("Can't handle: " + member.GetType ().ToString ());
357 }
358
359 protected virtual string GetTypeDeclaration (TypeDefinition type)
360 {
361 if (type == null)
362 throw new ArgumentNullException ("type");
363 StringBuilder buf = new StringBuilder (type.Name.Length);
364 _AppendTypeName (buf, type, null);
365 AppendGenericTypeConstraints (buf, type);
366 return buf.ToString ();
367 }
368
369 protected virtual string GetConstructorDeclaration (MethodDefinition constructor)
370 {
371 return GetConstructorName (constructor);
372 }
373
374 protected virtual string GetMethodDeclaration (MethodDefinition method)
375 {
376 if (method.HasCustomAttributes && method.CustomAttributes.Cast<CustomAttribute> ().Any (
377 ca => ca.GetDeclaringType () == "System.Diagnostics.Contracts.ContractInvariantMethodAttribute"))
378 return null;
379
380 // Special signature for destructors.
381 if (method.Name == "Finalize" && method.Parameters.Count == 0)
382 return GetFinalizerName (method);
383
384 StringBuilder buf = new StringBuilder ();
385
386 AppendVisibility (buf, method);
387 if (buf.Length == 0 &&
388 !(DocUtils.IsExplicitlyImplemented (method) && !method.IsSpecialName))
389 return null;
390
391 AppendModifiers (buf, method);
392
393 if (buf.Length != 0)
394 buf.Append (" ");
395
396 buf.Append (GetTypeName (method.ReturnType, new DynamicParserContext (method.MethodReturnType))).Append (" ");
397
398 AppendMethodName (buf, method);
399 AppendGenericMethod (buf, method).Append (" ");
400 AppendParameters (buf, method, method.Parameters);
401 AppendGenericMethodConstraints (buf, method);
402 return buf.ToString ();
403 }
404
405 protected virtual StringBuilder AppendMethodName (StringBuilder buf, MethodDefinition method)
406 {
407 return buf.Append (method.Name);
408 }
409
410 protected virtual string GetFinalizerName (MethodDefinition method)
411 {
412 return "Finalize";
413 }
414
415 protected virtual StringBuilder AppendVisibility (StringBuilder buf, MethodDefinition method)
416 {
417 return buf;
418 }
419
420 protected virtual StringBuilder AppendModifiers (StringBuilder buf, MethodDefinition method)
421 {
422 return buf;
423 }
424
425 protected virtual StringBuilder AppendGenericMethod (StringBuilder buf, MethodDefinition method)
426 {
427 return buf;
428 }
429
430 protected virtual StringBuilder AppendParameters (StringBuilder buf, MethodDefinition method, IList<ParameterDefinition> parameters)
431 {
432 return buf;
433 }
434
435 protected virtual StringBuilder AppendGenericMethodConstraints (StringBuilder buf, MethodDefinition method)
436 {
437 return buf;
438 }
439
440 protected virtual string GetPropertyDeclaration (PropertyDefinition property)
441 {
442 return GetPropertyName (property);
443 }
444
445 protected virtual string GetFieldDeclaration (FieldDefinition field)
446 {
447 return GetFieldName (field);
448 }
449
450 protected virtual string GetEventDeclaration (EventDefinition e)
451 {
452 return GetEventName (e);
453 }
454
455 protected virtual string GetAttachedEventDeclaration(Mono.Documentation.Util.AttachedEventDefinition e)
456 {
457 return $"see Add{e.Name}Handler, and Remove{e.Name}Handler";
458 }
459
460 protected virtual string GetAttachedPropertyDeclaration(AttachedPropertyDefinition a)
461 {
462 // check get and set member and craft string according
463 string getter = $"Get{a.Name}";
464 string setter = $"Set{a.Name}";
465
466 var get = a.GetMethod;
467 var set = a.SetMethod;
468
469 if (get != null && set == null)
470 return $"see {getter}";
471 else if (set != null && get == null)
472 return $"see {setter}";
473 else
474 return $"see {getter}, and {setter}";
475 }
476
477 public virtual bool IsSupported(TypeReference tref) => true;
478
479 public virtual bool IsSupported(MemberReference mref) => true;
480
481
482 protected static bool IsPublicEII (EventDefinition e)
483 {
484 bool isPublicEII = false;
485 if (e.AddMethod.HasOverrides)
486 {
487 var resolvedAddMethod = e.AddMethod.Overrides[0].Resolve ();
488 var resolvedInterface = e.AddMethod.Overrides[0].DeclaringType.Resolve ();
489 if (DocUtils.IsPublic (resolvedInterface) && resolvedAddMethod != null && resolvedAddMethod.IsPublic)
490 {
491 isPublicEII = true;
492 }
493 }
494
495 return isPublicEII;
496 }
497
498 public virtual MemberFormatter UsageFormatter { get; protected set; }
499
500 public static string GetLineEnding()
501 {
502 return "\n";
503 }
504
505 protected string CamelCase(string name)
506 {
507 return Char.ToLowerInvariant(name[0]) + name.Substring(1);
508 }
509 }
510 }