Debian Codegraph @

external/api-doc-tools/mdoc/Mono.Documentation/Updater/Formatters/CSharpFullMemberFormatter.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 CSharpFullMemberFormatter : MemberFormatter
14 {
15
16 public override string Language
17 {
18 get { return "C#"; }
19 }
20
21 protected override StringBuilder AppendNamespace (StringBuilder buf, TypeReference type)
22 {
23
24 string ns = DocUtils.GetNamespace (type);
25 if (GetCSharpType (type.FullName) == null && ns != null && ns.Length > 0 && ns != "System")
26 buf.Append (ns).Append ('.');
27 return buf;
28 }
29
30 protected virtual string GetCSharpType (string t)
31 {
32 // make sure there are no modifiers in the type string (add them back before returning)
33 string typeToCompare = t;
34 string[] splitType = null;
35 if (t.Contains (' '))
36 {
37 splitType = t.Split (' ');
38 typeToCompare = splitType[0];
39 }
40
41 switch (typeToCompare)
42 {
43 case "System.Byte": typeToCompare = "byte"; break;
44 case "System.SByte": typeToCompare = "sbyte"; break;
45 case "System.Int16": typeToCompare = "short"; break;
46 case "System.Int32": typeToCompare = "int"; break;
47 case "System.Int64": typeToCompare = "long"; break;
48
49 case "System.UInt16": typeToCompare = "ushort"; break;
50 case "System.UInt32": typeToCompare = "uint"; break;
51 case "System.UInt64": typeToCompare = "ulong"; break;
52
53 case "System.Single": typeToCompare = "float"; break;
54 case "System.Double": typeToCompare = "double"; break;
55 case "System.Decimal": typeToCompare = "decimal"; break;
56 case "System.Boolean": typeToCompare = "bool"; break;
57 case "System.Char": typeToCompare = "char"; break;
58 case "System.Void": typeToCompare = "void"; break;
59 case "System.String": typeToCompare = "string"; break;
60 case "System.Object": typeToCompare = "object"; break;
61 }
62
63 if (splitType != null)
64 {
65 // re-add modreq/modopt if it was there
66 splitType[0] = typeToCompare;
67 typeToCompare = string.Join (" ", splitType);
68 }
69 return typeToCompare == t ? null : typeToCompare;
70 }
71
72 protected override StringBuilder AppendTypeName (StringBuilder buf, TypeReference type, DynamicParserContext context)
73 {
74 if (context != null && context.TransformFlags != null &&
75 (context.TransformFlags.Count == 0 || context.TransformFlags[context.TransformIndex]))
76 {
77 context.TransformIndex++;
78 return buf.Append ("dynamic");
79 }
80
81 if (type is GenericParameter)
82 return AppendGenericParameterConstraints (buf, (GenericParameter)type, context).Append (type.Name);
83 string t = type.FullName;
84 if (!t.StartsWith ("System."))
85 {
86 return base.AppendTypeName (buf, type, context);
87 }
88
89 string s = GetCSharpType (t);
90 if (s != null)
91 {
92 if (context != null)
93 context.TransformIndex++;
94 return buf.Append (s);
95 }
96
97 return base.AppendTypeName (buf, type, context);
98 }
99
100 private StringBuilder AppendGenericParameterConstraints (StringBuilder buf, GenericParameter type, DynamicParserContext context)
101 {
102 if (MemberFormatterState != MemberFormatterState.WithinGenericTypeParameters)
103 return buf;
104 GenericParameterAttributes attrs = type.Attributes;
105 bool isout = (attrs & GenericParameterAttributes.Covariant) != 0;
106 bool isin = (attrs & GenericParameterAttributes.Contravariant) != 0;
107 if (isin)
108 buf.Append ("in ");
109 else if (isout)
110 buf.Append ("out ");
111 return buf;
112 }
113
114 protected override string GetTypeDeclaration (TypeDefinition type)
115 {
116 string visibility = GetTypeVisibility (type.Attributes);
117 if (visibility == null)
118 return null;
119
120 StringBuilder buf = new StringBuilder ();
121
122 buf.Append (visibility);
123 buf.Append (" ");
124
125 MemberFormatter full = new CSharpFullMemberFormatter ();
126
127 if (DocUtils.IsDelegate (type))
128 {
129 buf.Append ("delegate ");
130 MethodDefinition invoke = type.GetMethod ("Invoke");
131 buf.Append (full.GetName (invoke.ReturnType, new DynamicParserContext (invoke.MethodReturnType))).Append (" ");
132 buf.Append (GetName (type));
133 AppendParameters (buf, invoke, invoke.Parameters);
134 AppendGenericTypeConstraints (buf, type);
135 buf.Append (";");
136
137 return buf.ToString ();
138 }
139
140 if (type.IsAbstract && !type.IsInterface)
141 buf.Append ("abstract ");
142 if (type.IsSealed && !DocUtils.IsDelegate (type) && !type.IsValueType)
143 buf.Append ("sealed ");
144 buf.Replace ("abstract sealed", "static");
145
146 buf.Append (GetTypeKind (type));
147 buf.Append (" ");
148 buf.Append (GetCSharpType (type.FullName) == null
149 ? GetName (type)
150 : type.Name);
151
152 if (!type.IsEnum)
153 {
154 TypeReference basetype = type.BaseType;
155 if (basetype != null && basetype.FullName == "System.Object" || type.IsValueType) // FIXME
156 basetype = null;
157
158 List<string> interface_names = DocUtils.GetUserImplementedInterfaces (type)
159 .Select (iface => full.GetName (iface))
160 .OrderBy (s => s)
161 .ToList ();
162
163 if (basetype != null || interface_names.Count > 0)
164 buf.Append (" : ");
165
166 if (basetype != null)
167 {
168 buf.Append (full.GetName (basetype));
169 if (interface_names.Count > 0)
170 buf.Append (", ");
171 }
172
173 for (int i = 0; i < interface_names.Count; i++)
174 {
175 if (i != 0)
176 buf.Append (", ");
177 buf.Append (interface_names[i]);
178 }
179 AppendGenericTypeConstraints (buf, type);
180 }
181
182 return buf.ToString ();
183 }
184
185 static string GetTypeKind (TypeDefinition t)
186 {
187 if (t.IsEnum)
188 return "enum";
189 if (t.IsValueType)
190 return "struct";
191 if (t.IsClass || t.FullName == "System.Enum")
192 return "class";
193 if (t.IsInterface)
194 return "interface";
195 throw new ArgumentException (t.FullName);
196 }
197
198 static string GetTypeVisibility (TypeAttributes ta)
199 {
200 switch (ta & TypeAttributes.VisibilityMask)
201 {
202 case TypeAttributes.Public:
203 case TypeAttributes.NestedPublic:
204 return "public";
205
206 case TypeAttributes.NestedFamily:
207 return "protected";
208
209 case TypeAttributes.NestedFamORAssem:
210 return "protected internal";
211
212 default:
213 return null;
214 }
215 }
216
217 protected override StringBuilder AppendGenericTypeConstraints (StringBuilder buf, TypeReference type)
218 {
219 if (type.GenericParameters.Count == 0)
220 return buf;
221 return AppendConstraints (buf, type.GenericParameters);
222 }
223
224 private StringBuilder AppendConstraints (StringBuilder buf, IList<GenericParameter> genArgs)
225 {
226 foreach (GenericParameter genArg in genArgs)
227 {
228 GenericParameterAttributes attrs = genArg.Attributes;
229 #if NEW_CECIL
230 Mono.Collections.Generic.Collection<GenericParameterConstraint> constraints = genArg.Constraints;
231 #else
232 IList<TypeReference> constraints = genArg.Constraints;
233 #endif
234 if (attrs == GenericParameterAttributes.NonVariant && constraints.Count == 0)
235 continue;
236
237 bool isref = (attrs & GenericParameterAttributes.ReferenceTypeConstraint) != 0;
238 bool isvt = (attrs & GenericParameterAttributes.NotNullableValueTypeConstraint) != 0;
239 bool isnew = (attrs & GenericParameterAttributes.DefaultConstructorConstraint) != 0;
240 bool comma = false;
241
242 if (!isref && !isvt && !isnew && constraints.Count == 0)
243 continue;
244 buf.Append (" where ").Append (genArg.Name).Append (" : ");
245 if (isref)
246 {
247 buf.Append ("class");
248 comma = true;
249 }
250 else if (isvt)
251 {
252 buf.Append ("struct");
253 comma = true;
254 }
255 if (constraints.Count > 0 && !isvt)
256 {
257 if (comma)
258 buf.Append (", ");
259 #if NEW_CECIL
260 buf.Append (GetTypeName (constraints[0].ConstraintType));
261 for (int i = 1; i < constraints.Count; ++i)
262 buf.Append (", ").Append (GetTypeName (constraints[i].ConstraintType));
263 #else
264 buf.Append (GetTypeName (constraints[0]));
265 for (int i = 1; i < constraints.Count; ++i)
266 buf.Append (", ").Append (GetTypeName (constraints[i]));
267 #endif
268 }
269 if (isnew && !isvt)
270 {
271 if (comma)
272 buf.Append (", ");
273 buf.Append ("new()");
274 }
275 }
276 return buf;
277 }
278
279 protected override string GetConstructorDeclaration (MethodDefinition constructor)
280 {
281 StringBuilder buf = new StringBuilder ();
282 AppendVisibility (buf, constructor);
283 if (buf.Length == 0)
284 return null;
285
286 buf.Append (' ');
287 base.AppendTypeName (buf, constructor.DeclaringType.Name).Append (' ');
288 AppendParameters (buf, constructor, constructor.Parameters);
289 buf.Append (';');
290
291 return buf.ToString ();
292 }
293
294 protected override string GetMethodDeclaration (MethodDefinition method)
295 {
296 string decl = base.GetMethodDeclaration (method);
297 if (decl != null)
298 return decl + ";";
299 return null;
300 }
301
302 protected override StringBuilder AppendMethodName (StringBuilder buf, MethodDefinition method)
303 {
304 if (DocUtils.IsExplicitlyImplemented (method))
305 {
306 TypeReference iface;
307 MethodReference ifaceMethod;
308 DocUtils.GetInfoForExplicitlyImplementedMethod (method, out iface, out ifaceMethod);
309 return buf.Append (new CSharpMemberFormatter ().GetName (iface))
310 .Append ('.')
311 .Append (ifaceMethod.Name);
312 }
313
314 if (method.Name.StartsWith ("op_", StringComparison.Ordinal))
315 {
316 // this is an operator
317 switch (method.Name)
318 {
319 case "op_Implicit":
320 case "op_Explicit":
321 buf.Length--; // remove the last space, which assumes a member name is coming
322 return buf;
323 case "op_Addition":
324 case "op_UnaryPlus":
325 return buf.Append ("operator +");
326 case "op_Subtraction":
327 case "op_UnaryNegation":
328 return buf.Append ("operator -");
329 case "op_Division":
330 return buf.Append ("operator /");
331 case "op_Multiply":
332 return buf.Append ("operator *");
333 case "op_Modulus":
334 return buf.Append ("operator %");
335 case "op_BitwiseAnd":
336 return buf.Append ("operator &");
337 case "op_BitwiseOr":
338 return buf.Append ("operator |");
339 case "op_ExclusiveOr":
340 return buf.Append ("operator ^");
341 case "op_LeftShift":
342 return buf.Append ("operator <<");
343 case "op_RightShift":
344 return buf.Append ("operator >>");
345 case "op_LogicalNot":
346 return buf.Append ("operator !");
347 case "op_OnesComplement":
348 return buf.Append ("operator ~");
349 case "op_Decrement":
350 return buf.Append ("operator --");
351 case "op_Increment":
352 return buf.Append ("operator ++");
353 case "op_True":
354 return buf.Append ("operator true");
355 case "op_False":
356 return buf.Append ("operator false");
357 case "op_Equality":
358 return buf.Append ("operator ==");
359 case "op_Inequality":
360 return buf.Append ("operator !=");
361 case "op_LessThan":
362 return buf.Append ("operator <");
363 case "op_LessThanOrEqual":
364 return buf.Append ("operator <=");
365 case "op_GreaterThan":
366 return buf.Append ("operator >");
367 case "op_GreaterThanOrEqual":
368 return buf.Append ("operator >=");
369 default:
370 return base.AppendMethodName (buf, method);
371 }
372 }
373 else
374 return base.AppendMethodName (buf, method);
375 }
376
377 protected override StringBuilder AppendGenericMethodConstraints (StringBuilder buf, MethodDefinition method)
378 {
379 if (method.GenericParameters.Count == 0)
380 return buf;
381 return AppendConstraints (buf, method.GenericParameters);
382 }
383
384 protected override string RefTypeModifier
385 {
386 get { return ""; }
387 }
388
389 protected override string GetFinalizerName (MethodDefinition method)
390 {
391 StringBuilder buf = new StringBuilder();
392 base.AppendTypeName(buf, method.DeclaringType.Name);
393
394 return $"~{buf} ()";
395 }
396
397 protected override StringBuilder AppendVisibility (StringBuilder buf, MethodDefinition method)
398 {
399 if (method == null)
400 return buf;
401 if (method.IsPublic)
402 return buf.Append ("public");
403 if (method.IsFamily)
404 return buf.Append ("protected");
405 if (method.IsFamilyOrAssembly)
406 return buf.Append("protected internal");
407 return buf;
408 }
409
410 protected override StringBuilder AppendModifiers (StringBuilder buf, MethodDefinition method)
411 {
412 string modifiers = String.Empty;
413 if (method.IsStatic) modifiers += " static";
414 if (method.IsVirtual && !method.IsAbstract)
415 {
416 if ((method.Attributes & MethodAttributes.NewSlot) != 0) modifiers += " virtual";
417 else modifiers += " override";
418 }
419 TypeDefinition declType = (TypeDefinition)method.DeclaringType;
420 if (method.IsAbstract && !declType.IsInterface) modifiers += " abstract";
421 if (method.IsFinal) modifiers += " sealed";
422 if (modifiers == " virtual sealed") modifiers = "";
423
424 if ((method.ReturnType.IsRequiredModifier
425 && ((RequiredModifierType)method.ReturnType).ElementType.IsByReference)
426 || method.ReturnType.IsByReference)
427 {
428 modifiers += " ref";
429 }
430
431 if (method.ReturnType.IsRequiredModifier
432 && method.MethodReturnType.CustomAttributes.Any(attr => attr.AttributeType.FullName == "System.Runtime.CompilerServices.IsReadOnlyAttribute"))
433 {
434 modifiers += " readonly";
435 }
436
437 switch (method.Name)
438 {
439 case "op_Implicit":
440 modifiers += " implicit operator";
441 break;
442 case "op_Explicit":
443 modifiers += " explicit operator";
444 break;
445 }
446
447 return buf.Append (modifiers);
448 }
449
450 protected override StringBuilder AppendGenericMethod (StringBuilder buf, MethodDefinition method)
451 {
452 if (method.IsGenericMethod ())
453 {
454 IList<GenericParameter> args = method.GenericParameters;
455 if (args.Count > 0)
456 {
457 buf.Append ("<");
458 buf.Append (args[0].Name);
459 for (int i = 1; i < args.Count; ++i)
460 buf.Append (",").Append (args[i].Name);
461 buf.Append (">");
462 }
463 }
464 return buf;
465 }
466
467 protected override StringBuilder AppendParameters (StringBuilder buf, MethodDefinition method, IList<ParameterDefinition> parameters)
468 {
469 return AppendParameters (buf, method, parameters, '(', ')');
470 }
471
472 private StringBuilder AppendParameters (StringBuilder buf, MethodDefinition method, IList<ParameterDefinition> parameters, char begin, char end)
473 {
474 buf.Append (begin);
475
476 if (parameters.Count > 0)
477 {
478 if (DocUtils.IsExtensionMethod (method))
479 buf.Append ("this ");
480 AppendParameter (buf, parameters[0]);
481 for (int i = 1; i < parameters.Count; ++i)
482 {
483 buf.Append (", ");
484 AppendParameter (buf, parameters[i]);
485 }
486 }
487
488 return buf.Append (end);
489 }
490
491 private StringBuilder AppendParameter (StringBuilder buf, ParameterDefinition parameter)
492 {
493 if (parameter.ParameterType is ByReferenceType)
494 {
495 if (parameter.IsOut)
496 buf.Append ("out ");
497 else
498 buf.Append ("ref ");
499 }
500 if (parameter.HasCustomAttributes)
501 {
502 var isParams = parameter.CustomAttributes.Any (ca => ca.AttributeType.Name == "ParamArrayAttribute");
503 if (isParams)
504 buf.AppendFormat ("params ");
505 }
506 buf.Append (GetTypeName (parameter.ParameterType, new DynamicParserContext (parameter))).Append (" ");
507 buf.Append (parameter.Name);
508 if (parameter.HasDefault && parameter.IsOptional && parameter.HasConstant)
509 {
510 buf.AppendFormat (" = {0}", MDocUpdater.MakeAttributesValueString (parameter.Constant, parameter.ParameterType));
511 }
512 return buf;
513 }
514
515 protected override string GetPropertyDeclaration (PropertyDefinition property)
516 {
517 MethodDefinition method;
518
519 string get_visible = null;
520 if ((method = property.GetMethod) != null &&
521 (DocUtils.IsExplicitlyImplemented (method) ||
522 (!method.IsPrivate && !method.IsAssembly && !method.IsFamilyAndAssembly)))
523 get_visible = AppendVisibility (new StringBuilder (), method).ToString ();
524 string set_visible = null;
525 if ((method = property.SetMethod) != null &&
526 (DocUtils.IsExplicitlyImplemented (method) ||
527 (!method.IsPrivate && !method.IsAssembly && !method.IsFamilyAndAssembly)))
528 set_visible = AppendVisibility (new StringBuilder (), method).ToString ();
529
530 if ((set_visible == null) && (get_visible == null))
531 return null;
532
533 string visibility;
534 StringBuilder buf = new StringBuilder ();
535 if (get_visible != null && (set_visible == null || (set_visible != null && get_visible == set_visible)))
536 buf.Append (visibility = get_visible);
537 else if (set_visible != null && get_visible == null)
538 buf.Append (visibility = set_visible);
539 else
540 buf.Append (visibility = "public");
541
542 // Pick an accessor to use for static/virtual/override/etc. checks.
543 method = property.SetMethod;
544 if (method == null)
545 method = property.GetMethod;
546
547 string modifiers = String.Empty;
548 if (method.IsStatic) modifiers += " static";
549 if (method.IsVirtual && !method.IsAbstract)
550 {
551 if ((method.Attributes & MethodAttributes.NewSlot) != 0)
552 modifiers += " virtual";
553 else
554 modifiers += " override";
555 }
556 TypeDefinition declDef = (TypeDefinition)method.DeclaringType;
557 if (method.IsAbstract && !declDef.IsInterface)
558 modifiers += " abstract";
559 if (method.IsFinal)
560 modifiers += " sealed";
561 if (modifiers == " virtual sealed")
562 modifiers = "";
563 buf.Append (modifiers).Append (' ');
564
565 buf.Append (GetTypeName (property.PropertyType, new DynamicParserContext (property))).Append (' ');
566
567 IEnumerable<MemberReference> defs = property.DeclaringType.GetDefaultMembers ();
568 string name = property.Name;
569 foreach (MemberReference mi in defs)
570 {
571 if (mi == property)
572 {
573 name = "this";
574 break;
575 }
576 }
577 buf.Append (name == "this" ? name : DocUtils.GetPropertyName (property, NestedTypeSeparator));
578
579 if (property.Parameters.Count != 0)
580 {
581 AppendParameters (buf, method, property.Parameters, '[', ']');
582 }
583
584 buf.Append (" {");
585 if (get_visible != null)
586 {
587 if (get_visible != visibility)
588 buf.Append (' ').Append (get_visible);
589 buf.Append (" get;");
590 }
591 if (set_visible != null)
592 {
593 if (set_visible != visibility)
594 buf.Append (' ').Append (set_visible);
595 buf.Append (" set;");
596 }
597 buf.Append (" }");
598
599 return buf[0] != ' ' ? buf.ToString () : buf.ToString (1, buf.Length - 1);
600 }
601
602 protected override string GetFieldDeclaration (FieldDefinition field)
603 {
604 TypeDefinition declType = (TypeDefinition)field.DeclaringType;
605 if (declType.IsEnum && field.Name == "value__")
606 return null; // This member of enums aren't documented.
607
608 StringBuilder buf = new StringBuilder ();
609 AppendFieldVisibility (buf, field);
610 if (buf.Length == 0)
611 return null;
612
613 if (declType.IsEnum)
614 return field.Name;
615
616 if (field.IsStatic && !field.IsLiteral)
617 buf.Append (" static");
618 if (field.IsInitOnly)
619 buf.Append (" readonly");
620 if (field.IsLiteral)
621 buf.Append (" const");
622
623 buf.Append (' ').Append (GetTypeName (field.FieldType, new DynamicParserContext (field))).Append (' ');
624 buf.Append (field.Name);
625 DocUtils.AppendFieldValue (buf, field);
626 buf.Append (';');
627
628 return buf.ToString ();
629 }
630
631 static void AppendFieldVisibility (StringBuilder buf, FieldDefinition field)
632 {
633 if (field.IsPublic)
634 {
635 buf.Append("public");
636 return;
637 }
638 if (field.IsFamily)
639 {
640 buf.Append("protected");
641 }
642 if ( field.IsFamilyOrAssembly)
643 {
644 buf.Append("protected internal");
645 }
646 }
647
648 protected override string GetEventDeclaration (EventDefinition e)
649 {
650 StringBuilder buf = new StringBuilder ();
651
652 if (AppendVisibility (buf, e.AddMethod).Length == 0 && !IsPublicEII (e))
653 {
654 return null;
655 }
656 if (e.DeclaringType.IsInterface)
657 buf.Clear ();
658
659 AppendModifiers (buf, e.AddMethod);
660
661 buf.Append (buf.Length == 0 ? "event " : " event ");
662 buf.Append (GetTypeName (e.EventType, new DynamicParserContext (e.AddMethod.Parameters[0]))).Append (' ');
663 buf.Append (e.Name).Append (';');
664
665 return buf.ToString ();
666 }
667 }
668 }