Debian Codegraph @

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

raw
1 using System;
2 using System.Collections.Generic;
3 using System.Globalization;
4 using System.Linq;
5 using System.Text;
6
7 using Mono.Cecil;
8
9 using Mono.Documentation.Util;
10
11 namespace Mono.Documentation.Updater
12 {
13 public class ILFullMemberFormatter : MemberFormatter
14 {
15
16 public override string Language
17 {
18 get { return "ILAsm"; }
19 }
20
21 protected override string NestedTypeSeparator
22 {
23 get
24 {
25 return "/";
26 }
27 }
28
29 protected override StringBuilder AppendNamespace (StringBuilder buf, TypeReference type)
30 {
31 if (GetBuiltinType (type.FullName) != null)
32 return buf;
33 string ns = DocUtils.GetNamespace (type);
34 if (ns != null && ns.Length > 0)
35 {
36 if (type.IsValueType)
37 buf.Append ("valuetype ");
38 else
39 buf.Append ("class ");
40 buf.Append (ns).Append ('.');
41 }
42 return buf;
43 }
44
45 protected static string GetBuiltinType (string t)
46 {
47 switch (t)
48 {
49 case "System.Byte": return "unsigned int8";
50 case "System.SByte": return "int8";
51 case "System.Int16": return "int16";
52 case "System.Int32": return "int32";
53 case "System.Int64": return "int64";
54 case "System.IntPtr": return "native int";
55
56 case "System.UInt16": return "unsigned int16";
57 case "System.UInt32": return "unsigned int32";
58 case "System.UInt64": return "unsigned int64";
59 case "System.UIntPtr": return "native unsigned int";
60
61 case "System.Single": return "float32";
62 case "System.Double": return "float64";
63 case "System.Boolean": return "bool";
64 case "System.Char": return "char";
65 case "System.Void": return "void";
66 case "System.String": return "string";
67 case "System.Object": return "object";
68 }
69 return null;
70 }
71
72 protected override StringBuilder AppendTypeName (StringBuilder buf, string typename)
73 {
74 return buf.Append (typename);
75 }
76
77 protected override StringBuilder AppendTypeName (StringBuilder buf, TypeReference type, DynamicParserContext context)
78 {
79 if (type is GenericParameter)
80 {
81 AppendGenericParameterConstraints (buf, (GenericParameter)type).Append (type.Name);
82 return buf;
83 }
84
85 string s = GetBuiltinType (type.FullName);
86 if (s != null)
87 {
88 return buf.Append (s);
89 }
90 return base.AppendTypeName (buf, type, context);
91 }
92
93 private StringBuilder AppendGenericParameterConstraints (StringBuilder buf, GenericParameter type)
94 {
95 if (MemberFormatterState != MemberFormatterState.WithinGenericTypeParameters)
96 {
97 return buf.Append (type.Owner is TypeReference ? "!" : "!!");
98 }
99 GenericParameterAttributes attrs = type.Attributes;
100 if ((attrs & GenericParameterAttributes.ReferenceTypeConstraint) != 0)
101 buf.Append ("class ");
102 if ((attrs & GenericParameterAttributes.NotNullableValueTypeConstraint) != 0)
103 buf.Append ("struct ");
104 if ((attrs & GenericParameterAttributes.DefaultConstructorConstraint) != 0)
105 buf.Append (".ctor ");
106 MemberFormatterState = 0;
107
108 #if NEW_CECIL
109 Mono.Collections.Generic.Collection<GenericParameterConstraint> constraints = type.Constraints;
110 if (constraints.Count > 0)
111 {
112 var full = new ILFullMemberFormatter ();
113 buf.Append ("(").Append (full.GetName (constraints[0].ConstraintType));
114 for (int i = 1; i < constraints.Count; ++i)
115 {
116 buf.Append (", ").Append (full.GetName (constraints[i].ConstraintType));
117 }
118 buf.Append (") ");
119 }
120 #else
121 IList<TypeReference> constraints = type.Constraints;
122 if (constraints.Count > 0)
123 {
124 var full = new ILFullMemberFormatter ();
125 buf.Append ("(").Append (full.GetName (constraints[0]));
126 for (int i = 1; i < constraints.Count; ++i)
127 {
128 buf.Append (", ").Append (full.GetName (constraints[i]));
129 }
130 buf.Append (") ");
131 }
132 #endif
133 MemberFormatterState = MemberFormatterState.WithinGenericTypeParameters;
134
135 if ((attrs & GenericParameterAttributes.Covariant) != 0)
136 buf.Append ("+ ");
137 if ((attrs & GenericParameterAttributes.Contravariant) != 0)
138 buf.Append ("- ");
139 return buf;
140 }
141
142 protected override string GetTypeDeclaration (TypeDefinition type)
143 {
144 string visibility = GetTypeVisibility (type.Attributes);
145 if (visibility == null)
146 return null;
147
148 StringBuilder buf = new StringBuilder ();
149
150 buf.Append (".class ");
151 if (type.IsNested)
152 buf.Append ("nested ");
153 buf.Append (visibility).Append (" ");
154 if (type.IsInterface)
155 buf.Append ("interface ");
156 if (type.IsSequentialLayout)
157 buf.Append ("sequential ");
158 if (type.IsAutoLayout)
159 buf.Append ("auto ");
160 if (type.IsAnsiClass)
161 buf.Append ("ansi ");
162 if (type.IsAbstract)
163 buf.Append ("abstract ");
164 if (type.IsSerializable)
165 buf.Append ("serializable ");
166 if (type.IsSealed)
167 buf.Append ("sealed ");
168 if (type.IsBeforeFieldInit)
169 buf.Append ("beforefieldinit ");
170 var state = MemberFormatterState;
171 MemberFormatterState = MemberFormatterState.WithinGenericTypeParameters;
172 buf.Append (GetName (type));
173 MemberFormatterState = state;
174 var full = new ILFullMemberFormatter ();
175 if (type.BaseType != null)
176 {
177 buf.Append (" extends ");
178 if (type.BaseType.FullName == "System.Object")
179 buf.Append ("System.Object");
180 else
181 buf.Append (full.GetName (type.BaseType).Substring ("class ".Length));
182 }
183 bool first = true;
184 foreach (var name in type.Interfaces.Where (i => MDocUpdater.IsPublic (i.InterfaceType.Resolve ()))
185 .Select (i => full.GetName (i.InterfaceType))
186 .OrderBy (n => n))
187 {
188 if (first)
189 {
190 buf.Append (" implements ");
191 first = false;
192 }
193 else
194 {
195 buf.Append (", ");
196 }
197 buf.Append (name);
198 }
199
200 return buf.ToString ();
201 }
202
203 protected override StringBuilder AppendGenericType (StringBuilder buf, TypeReference type, DynamicParserContext context, bool appendGeneric = true)
204 {
205 List<TypeReference> decls = DocUtils.GetDeclaringTypes (
206 type is GenericInstanceType ? type.GetElementType () : type);
207 bool first = true;
208 foreach (var decl in decls)
209 {
210 TypeReference declDef = decl.Resolve () ?? decl;
211 if (!first)
212 {
213 buf.Append (NestedTypeSeparator);
214 }
215 first = false;
216 AppendTypeName (buf, declDef, context);
217 }
218 buf.Append ('<');
219 first = true;
220 foreach (TypeReference arg in GetGenericArguments (type))
221 {
222 if (!first)
223 buf.Append (", ");
224 first = false;
225 _AppendTypeName (buf, arg, context);
226 }
227 buf.Append ('>');
228 return buf;
229 }
230
231 static string GetTypeVisibility (TypeAttributes ta)
232 {
233 switch (ta & TypeAttributes.VisibilityMask)
234 {
235 case TypeAttributes.Public:
236 case TypeAttributes.NestedPublic:
237 return "public";
238
239 case TypeAttributes.NestedFamily:
240 case TypeAttributes.NestedFamORAssem:
241 return "protected";
242
243 default:
244 return null;
245 }
246 }
247
248 protected override string GetConstructorDeclaration (MethodDefinition constructor)
249 {
250 return GetMethodDeclaration (constructor);
251 }
252
253 protected override string GetMethodDeclaration (MethodDefinition method)
254 {
255 if (method.IsPrivate && !DocUtils.IsExplicitlyImplemented (method))
256 return null;
257
258 var buf = new StringBuilder ();
259 buf.Append (".method ");
260 AppendVisibility (buf, method);
261 if (method.IsStatic)
262 buf.Append ("static ");
263 if (method.IsHideBySig)
264 buf.Append ("hidebysig ");
265 if (method.IsPInvokeImpl && method.PInvokeInfo != null)
266 {
267 var info = method.PInvokeInfo;
268
269 buf.Append ("pinvokeimpl (\"")
270 .Append (info.Module.Name)
271 .Append ("\" as \"")
272 .Append (info.EntryPoint)
273 .Append ("\"");
274
275 if (info.IsCharSetAuto)
276 buf.Append (" auto");
277 if (info.IsCharSetUnicode)
278 buf.Append (" unicode");
279 if (info.IsCharSetAnsi)
280 buf.Append (" ansi");
281 if (info.IsCallConvCdecl)
282 buf.Append (" cdecl");
283 if (info.IsCallConvStdCall)
284 buf.Append (" stdcall");
285 if (info.IsCallConvWinapi)
286 buf.Append (" winapi");
287 if (info.IsCallConvThiscall)
288 buf.Append (" thiscall");
289 if (info.SupportsLastError)
290 buf.Append (" lasterr");
291 buf.Append (")");
292 }
293 if (method.IsSpecialName)
294 buf.Append ("specialname ");
295 if (method.IsRuntimeSpecialName)
296 buf.Append ("rtspecialname ");
297 if (method.IsNewSlot)
298 buf.Append ("newslot ");
299 if (method.IsVirtual)
300 buf.Append ("virtual ");
301 if (!method.IsStatic)
302 buf.Append ("instance ");
303 _AppendTypeName (buf, method.ReturnType, new DynamicParserContext (method.MethodReturnType));
304 buf.Append (' ')
305 .Append (method.Name);
306 if (method.IsGenericMethod ())
307 {
308 var state = MemberFormatterState;
309 MemberFormatterState = MemberFormatterState.WithinGenericTypeParameters;
310 IList<GenericParameter> args = method.GenericParameters;
311 if (args.Count > 0)
312 {
313 buf.Append ("<");
314 _AppendTypeName (buf, args[0], null);
315 for (int i = 1; i < args.Count; ++i)
316 _AppendTypeName (buf.Append (", "), args[i], null);
317 buf.Append (">");
318 }
319 MemberFormatterState = state;
320 }
321
322 buf.Append ('(');
323 bool first = true;
324 for (int i = 0; i < method.Parameters.Count; ++i)
325 {
326 var param = method.Parameters[i];
327 if (!first)
328 buf.Append (", ");
329 first = false;
330
331 if (param.IsOut) buf.Append ("[out] ");
332 else if (param.IsIn) buf.Append ("[in]");
333
334 _AppendTypeName (buf, param.ParameterType, new DynamicParserContext (param));
335 if (param.ParameterType.IsByReference) buf.Append ("&");
336 buf.Append (' ');
337 buf.Append (param.Name);
338 }
339 buf.Append (')');
340 if (method.IsIL)
341 buf.Append (" cil");
342 if (method.IsRuntime)
343 buf.Append (" runtime");
344 if (method.IsManaged)
345 buf.Append (" managed");
346
347 return buf.ToString ();
348 }
349
350 protected override StringBuilder AppendMethodName (StringBuilder buf, MethodDefinition method)
351 {
352 if (DocUtils.IsExplicitlyImplemented (method))
353 {
354 TypeReference iface;
355 MethodReference ifaceMethod;
356 DocUtils.GetInfoForExplicitlyImplementedMethod (method, out iface, out ifaceMethod);
357 return buf.Append (new CSharpMemberFormatter ().GetName (iface))
358 .Append ('.')
359 .Append (ifaceMethod.Name);
360 }
361 return base.AppendMethodName (buf, method);
362 }
363
364 protected override string RefTypeModifier
365 {
366 get { return ""; }
367 }
368
369 protected override StringBuilder AppendVisibility (StringBuilder buf, MethodDefinition method)
370 {
371 if (method.IsPublic)
372 return buf.Append ("public ");
373 if (method.IsFamilyAndAssembly)
374 return buf.Append ("familyandassembly");
375 if (method.IsFamilyOrAssembly)
376 return buf.Append ("familyorassembly");
377 if (method.IsFamily)
378 return buf.Append ("family");
379 return buf;
380 }
381
382 protected override StringBuilder AppendModifiers (StringBuilder buf, MethodDefinition method)
383 {
384 string modifiers = String.Empty;
385 if (method.IsStatic) modifiers += " static";
386 if (method.IsVirtual && !method.IsAbstract)
387 {
388 if ((method.Attributes & MethodAttributes.NewSlot) != 0) modifiers += " virtual";
389 else modifiers += " override";
390 }
391 TypeDefinition declType = (TypeDefinition)method.DeclaringType;
392 if (method.IsAbstract && !declType.IsInterface) modifiers += " abstract";
393 if (method.IsFinal) modifiers += " sealed";
394 if (modifiers == " virtual sealed") modifiers = "";
395
396 return buf.Append (modifiers);
397 }
398
399 protected override StringBuilder AppendGenericMethod (StringBuilder buf, MethodDefinition method)
400 {
401 if (method.IsGenericMethod ())
402 {
403 IList<GenericParameter> args = method.GenericParameters;
404 if (args.Count > 0)
405 {
406 buf.Append ("<");
407 buf.Append (args[0].Name);
408 for (int i = 1; i < args.Count; ++i)
409 buf.Append (",").Append (args[i].Name);
410 buf.Append (">");
411 }
412 }
413 return buf;
414 }
415
416 protected override StringBuilder AppendParameters (StringBuilder buf, MethodDefinition method, IList<ParameterDefinition> parameters)
417 {
418 return AppendParameters (buf, method, parameters, '(', ')');
419 }
420
421 private StringBuilder AppendParameters (StringBuilder buf, MethodDefinition method, IList<ParameterDefinition> parameters, char begin, char end)
422 {
423 buf.Append (begin);
424
425 if (parameters.Count > 0)
426 {
427 if (DocUtils.IsExtensionMethod (method))
428 buf.Append ("this ");
429 AppendParameter (buf, parameters[0]);
430 for (int i = 1; i < parameters.Count; ++i)
431 {
432 buf.Append (", ");
433 AppendParameter (buf, parameters[i]);
434 }
435 }
436
437 return buf.Append (end);
438 }
439
440 private StringBuilder AppendParameter (StringBuilder buf, ParameterDefinition parameter)
441 {
442 if (parameter.ParameterType is ByReferenceType)
443 {
444 if (parameter.IsOut)
445 buf.Append ("out ");
446 else
447 buf.Append ("ref ");
448 }
449 buf.Append (GetName (parameter.ParameterType)).Append (" ");
450 return buf.Append (parameter.Name);
451 }
452
453 protected override string GetPropertyDeclaration (PropertyDefinition property)
454 {
455 MethodDefinition gm = null, sm = null;
456
457 string get_visible = null;
458 if ((gm = property.GetMethod) != null &&
459 (DocUtils.IsExplicitlyImplemented (gm) ||
460 (!gm.IsPrivate && !gm.IsAssembly && !gm.IsFamilyAndAssembly)))
461 get_visible = AppendVisibility (new StringBuilder (), gm).ToString ();
462 string set_visible = null;
463 if ((sm = property.SetMethod) != null &&
464 (DocUtils.IsExplicitlyImplemented (sm) ||
465 (!sm.IsPrivate && !sm.IsAssembly && !sm.IsFamilyAndAssembly)))
466 set_visible = AppendVisibility (new StringBuilder (), sm).ToString ();
467
468 if ((set_visible == null) && (get_visible == null))
469 return null;
470
471 StringBuilder buf = new StringBuilder ()
472 .Append (".property ");
473 if (!(gm ?? sm).IsStatic)
474 buf.Append ("instance ");
475 _AppendTypeName (buf, property.PropertyType, new DynamicParserContext (property));
476 buf.Append (' ').Append (property.Name);
477 if (!property.HasParameters || property.Parameters.Count == 0)
478 return buf.ToString ();
479
480 buf.Append ('(');
481 bool first = true;
482 foreach (ParameterDefinition p in property.Parameters)
483 {
484 if (!first)
485 buf.Append (", ");
486 first = false;
487 _AppendTypeName (buf, p.ParameterType, new DynamicParserContext (p));
488 }
489 buf.Append (')');
490
491 return buf.ToString ();
492 }
493
494 protected override string GetFieldDeclaration (FieldDefinition field)
495 {
496 TypeDefinition declType = (TypeDefinition)field.DeclaringType;
497 if (declType.IsEnum && field.Name == "value__")
498 return null; // This member of enums aren't documented.
499
500 StringBuilder buf = new StringBuilder ();
501 AppendFieldVisibility (buf, field);
502 if (buf.Length == 0)
503 return null;
504
505 buf.Insert (0, ".field ");
506
507 if (field.IsStatic)
508 buf.Append ("static ");
509 if (field.IsInitOnly)
510 buf.Append ("initonly ");
511 if (field.IsLiteral)
512 buf.Append ("literal ");
513 _AppendTypeName (buf, field.FieldType, new DynamicParserContext (field));
514 buf.Append (' ').Append (field.Name);
515 AppendFieldValue (buf, field);
516
517 return buf.ToString ();
518 }
519
520 static StringBuilder AppendFieldVisibility (StringBuilder buf, FieldDefinition field)
521 {
522 if (field.IsPublic)
523 return buf.Append ("public ");
524 if (field.IsFamilyAndAssembly)
525 return buf.Append ("familyandassembly ");
526 if (field.IsFamilyOrAssembly)
527 return buf.Append ("familyorassembly ");
528 if (field.IsFamily)
529 return buf.Append ("family ");
530 return buf;
531 }
532
533 static StringBuilder AppendFieldValue (StringBuilder buf, FieldDefinition field)
534 {
535 // enums have a value__ field, which we ignore
536 if (field.DeclaringType.IsGenericType ())
537 return buf;
538 if (field.HasConstant && field.IsLiteral)
539 {
540 object val = null;
541 try
542 {
543 val = field.Constant;
544 }
545 catch
546 {
547 return buf;
548 }
549 if (val == null)
550 buf.Append (" = ").Append ("null");
551 else if (val is Enum)
552 buf.Append (" = ")
553 .Append (GetBuiltinType (field.DeclaringType.GetUnderlyingType ().FullName))
554 .Append ('(')
555 .Append (val.ToString ())
556 .Append (')');
557 else if (val is IFormattable)
558 {
559 string value = ((IFormattable)val).ToString (null, CultureInfo.InvariantCulture);
560 buf.Append (" = ");
561 if (val is string)
562 buf.Append ("\"" + value + "\"");
563 else
564 buf.Append (GetBuiltinType (field.DeclaringType.GetUnderlyingType ().FullName))
565 .Append ('(')
566 .Append (value)
567 .Append (')');
568 }
569 }
570 return buf;
571 }
572
573 protected override string GetEventDeclaration (EventDefinition e)
574 {
575 StringBuilder buf = new StringBuilder ();
576 if (AppendVisibility (buf, e.AddMethod).Length == 0 && !IsPublicEII (e))
577 {
578 return null;
579 }
580
581 buf.Length = 0;
582 buf.Append (".event ")
583 .Append (GetName (e.EventType))
584 .Append (' ')
585 .Append (e.Name);
586
587 return buf.ToString ();
588 }
589 }
590 }